Slovník pojmů

Namespace

Namespace neboli jmenný prostor organizuje názvy ve větším kódu. Není adresář, Composer balíček, modul ani bezpečnostní hranice, přesto s některými z nich často spolupracuje.

Stručná definice

Jména bez zbytečných kolizí.

Dvě knihovny mohou mít třídu Order nebo Logger. Namespace je rozliší plně kvalifikovaným jménem, například \App\Order\Domain\Order. V souboru lze pak importovat kratší jméno přes use nebo použít alias.

V PHP se namespace deklaruje v souboru. Composer může přes PSR-4 mapovat prefix namespace na základní adresář a automaticky najít třídu. Jde o častou konvenci, nikoli technickou totožnost namespace a adresáře.

Jaký problém řeší

Udržuje větší projekt přehledný a kolizím odolný.

Namespace dává třídám souvislý kontext bez nutnosti vymýšlet globálně unikátní krátké názvy.

oddělení aplikace a kódu nainstalovaných knihoven
rozlišení stejně pojmenovaných tříd
organizace vrstev nebo modulů projektu
napojení názvů na PSR-4 autoloading

Praktický příklad

Jmenný prostor aplikační vrstvy objednávek

App\Order\Application, App\Order\Domain a App\Order\Infrastructure jsou jedna možná organizace. Nejde o univerzální pravidlo ani důkaz správné architektury; příliš hluboké větvení může orientaci naopak zhoršit.

use importuje jméno do souboru a alias SystemClock odliší dvě třídy se stejným krátkým názvem. use zde nevytváří objekt ani neprovádí dependency injection.

PHP

<?php

namespace App\Order\Application;

use App\Order\Domain\Order;
use App\Shared\Clock as SystemClock;

final class PlaceOrder
{
    public function __construct(private SystemClock $clock) {}

    public function handle(Order $order): void {}
}

Jak funguje

Od názvu třídy k souboru

PSR-4 je běžný způsob nalezení třídy; samotný namespace neurčuje fyzickou cestu.

Plně kvalifikované jméno Například \App\Order\Domain\Order určuje přesný název třídy.
Import nebo alias use zpřístupní krátké jméno v aktuálním souboru.
PSR-4 prefix Autoloader může prefix App\ mapovat na src/.
Soubor třídy Autoloader načte odpovídající soubor podle své konfigurace.

Hlavní části a varianty

Názvy, importy a autoloading nejsou jedna věc.

Rozlišení těchto hranic brání chybnému předpokladu, že změna adresáře automaticky změní namespace.

Plně kvalifikované jméno

Obsahuje celý namespace a název; v PHP začíná zpětným lomítkem.

Relativní jméno a use

Krátké jméno se vyhodnocuje v kontextu namespace nebo importu; use může nastavit alias.

PSR-4

Standardizuje mapování prefixu názvu na adresář pro autoloading, nikoli architekturu projektu.

Hranice pojmu

Namespace není balíček, JavaScript modul ani XML namespace a nezajišťuje přístupová oprávnění.

Omezení a časté chyby

Přehledný název nemá být příliš hluboký.

Co pomáhá

stabilní prefix pro aplikaci a knihovny
krátké importy a alias při skutečné kolizi
PSR-4 konfigurace odpovídající zdrojovým adresářům

Rizika

považovat namespace za bezpečnostní hranici
zaměnit use za vytvoření nebo injektování objektu
vytvářet příliš hluboké větvení bez přínosu
předpokládat, že namespace je vždy adresář

Praktické použití

Jmenné prostory mají podporovat orientaci, ne nahradit návrh.

Ve větším projektu mohou názvy App\Order\Application nebo App\Order\Domain vyjádřit kontext, ale samy nevynutí povolené závislosti. Na ty jsou potřeba kontrakty, review a případně automatické kontroly.

Při změně namespace zkontrolujte mapování autoloadingu, importy, testy a veřejné API knihoven. Hromadné přejmenování bez těchto kroků vede k chybám až za běhu.

Namespace je logický název, zatímco adresář je fyzické umístění souboru a Composer balíček distribuční jednotka. PSR-4 je často propojí, ale neurčuje architekturu ani bezpečnostní hranici. Stejně tak use pouze importuje nebo aliasuje symbol; dependency injection předává hotový objekt. Toto rozlišení udrží názvy i závislosti čitelné.

V knihovně navíc může být prefix součástí veřejného API. Změna jmenného prostoru pak není jen kosmetická úprava cesty: spotřebitelé musí změnit importy a autoloading. V aplikaci i knihovně proto pomáhá držet hierarchii dostatečně krátkou, vybírat názvy podle skutečného kontextu a po přejmenování spustit testy.

Jmenný prostor neomezuje viditelnost třídy a sám nevynucuje směr závislostí mezi vrstvami. Ochranu řeší přístupová pravidla, autentizace, autorizace a návrh aplikace. Namespace jen zajišťuje, že jméno typu má jednoznačný kontext; nemá nahrazovat architektonickou hranici, kterou projekt skutečně potřebuje.

Dobrá konvence namespace také neznamená, že každá technická drobnost potřebuje další úroveň názvu. Prefix má pomoci čtenáři rychle najít kontext třídy, ne opakovat všechny adresáře projektu. Když je plně kvalifikované jméno dlouhé nebo importy neustále kolidují, je užitečné prověřit pojmenování komponent a hranice modulů, ne jen přidat další podadresář.

Kontrola změny

Ověřte význam názvu i cestu, která ho načítá.

Jmenný prostor by měl pomoci najít typ a pochopit jeho kontext.

rozlišit plný název, import a alias
ověřit PSR-4 mapování po změně adresáře
nepoužívat use jako termín pro DI
neztotožňovat namespace s bezpečností nebo modulem

Časté otázky

Namespace v PHP

Je namespace adresář?

Ne. PSR-4 je často mapuje, ale namespace je logický název a adresář je fyzická organizace souborů.

Co dělá use?

Importuje nebo aliasuje jméno v aktuálním souboru; nevytváří objekt.

Potřebuji Composer pro namespace?

Namespace lze psát bez Composeru, Composer ale běžně zajišťuje PSR-4 autoloading.

Je namespace balíček?

Ne. Balíček je distribuční jednotka a může obsahovat několik jmenných prostorů.

Osobní zkušenost

Názvy mají urychlit orientaci v kódu, ne skrýt jeho hranice.

V PHP projektech používám namespace a PSR-4 jako čitelnou konvenci vedle jasné architektury a závislostí.

Zobrazit přístup k architektuře Nezávazně probrat projekt