Przestrzenie nazw w PHP: namespace, use i aliasy

Przestrzeń nazw w PHP umieszcza klasy, funkcje i stałe pod prefiksem, żeby ich nazwy nie kolidowały z cudzymi. Deklarujesz ją przez namespace App\Models; jako pierwszą instrukcję pliku, a inne pliki odwołują się do klasy jako \App\Models\User albo importują ją przez use App\Models\User; i piszą samo User.

<?php
namespace App\Models;

class User
{
    public function __construct(public string $name) {}
}

function greet(User $u): string
{
    return "Hello, {$u->name}";
}

$u = new User('Ada');
echo greet($u), "\n";
echo User::class, "\n";
echo __NAMESPACE__, "\n";
echo get_class($u), "\n";

Wewnątrz przestrzeni nazw User oznacza App\Models\User. User::class daje pełną nazwę jako string, niczego nie tworząc, co przydaje się przy logowaniu i w autoloaderach.

Dwie przestrzenie nazw w jednym pliku

Prawdziwy projekt umieszcza jedną przestrzeń nazw w każdym pliku. Na potrzeby samodzielnego przykładu jeden plik może zawierać kilka przestrzeni nazw, jeśli każda jest otoczona nawiasami klamrowymi. Kod, który nie należy do żadnej przestrzeni nazw, trafia do namespace { }:

<?php
namespace Shop {
    class Order
    {
        public function label(): string { return 'shop order'; }
    }
}

namespace Kitchen {
    class Order
    {
        public function label(): string { return 'kitchen ticket'; }
    }
}

namespace {
    // Global code: use the fully qualified names
    $a = new \Shop\Order();
    $b = new \Kitchen\Order();
    echo get_class($a), ': ', $a->label(), "\n";
    echo get_class($b), ': ', $b->label(), "\n";
}

Dwie klasy o nazwie Order istnieją obok siebie, bo ich pełne nazwy się różnią. To dokładnie ten problem, który rozwiązują przestrzenie nazw, gdy instalujesz biblioteki: twoje Order, Order biblioteki płatności i Order biblioteki PDF przestają się gryźć.

Import przez use i aliasy przez as

Pisanie wszędzie \Shop\Order wprowadza szum. use na górze pliku (lub bloku przestrzeni nazw) importuje nazwę, aby można było używać krótkiej formy. Gdy dwa importy kończyłyby się tą samą krótką nazwą, as nadaje jednemu z nich inną nazwę:

<?php
namespace Shop {
    class Order { public string $kind = 'shop'; }
    class Invoice { public string $kind = 'invoice'; }
}

namespace Kitchen {
    class Order { public string $kind = 'kitchen'; }
}

namespace App {
    use Shop\Order;
    use Shop\Invoice;
    use Kitchen\Order as KitchenOrder;

    $orders = [new Order(), new KitchenOrder(), new Invoice()];
    foreach ($orders as $o) {
        echo get_class($o), ' -> ', $o->kind, "\n";
    }
    echo KitchenOrder::class, "\n";
}

use tylko tworzy krótką nazwę dla reszty pliku. Nie wczytuje pliku ani nie uruchamia kodu i działa tak samo niezależnie od tego, czy klasa już istnieje. Dozwolone są też importy grupowe: use Shop\{Order, Invoice};.

use function i use const

Funkcje i stałe z przestrzeni nazw importuje się przez use function i use const:

<?php
namespace Utils\Text {
    const ELLIPSIS = '...';

    function shorten(string $s, int $max): string
    {
        return mb_strlen($s) > $max ? mb_substr($s, 0, $max) . ELLIPSIS : $s;
    }
}

namespace App {
    use function Utils\Text\shorten;
    use const Utils\Text\ELLIPSIS;

    echo shorten('Namespaces keep names apart', 10), "\n";
    echo 'Marker: ', ELLIPSIS, "\n";
    echo \Utils\Text\shorten('Fully qualified call works too', 15), "\n";
}

Klasy globalne wymagają ukośnika wstecznego

Wewnątrz przestrzeni nazw niekwalifikowana nazwa klasy jest rozwiązywana względem tej przestrzeni, więc new DateTime() wewnątrz namespace App; szuka App\DateTime. Z funkcjami i stałymi jest inaczej: jeśli App\strlen nie istnieje, PHP wraca do globalnego strlen. Klasy nigdy nie wracają.

<?php
namespace App;

echo strlen('works'), "\n";        // functions fall back to global
echo PHP_INT_SIZE, "\n";               // so do constants

try {
    $d = new DateTime('2026-03-14');
} catch (\Error $e) {
    echo $e->getMessage(), "\n";
}

$d = new \DateTime('2026-03-14');  // leading backslash: the global class
echo $d->format('D, d M Y'), "\n";

catch (\Error $e) potrzebowało ukośnika wstecznego z tego samego powodu: bez niego PHP szukałoby App\Error, nigdy nie dopasowałoby prawdziwego błędu, a skrypt zatrzymałby się z nieprzechwyconym Error. Napraw to początkowym ukośnikiem wstecznym, jak wyżej, albo przez use DateTime; na górze pliku. To samo dotyczy \Exception, \Throwable i każdej innej klasy wbudowanej; ich przechwytywanie opisuje strona try catch.

Autoloading i PSR-4

W projekcie każda klasa leży we własnym pliku, a ścieżka pliku odpowiada przestrzeni nazw. Konwencją jest PSR-4: prefiks przestrzeni nazw odpowiada folderowi bazowemu, a reszta nazwy staje się ścieżką. Autoloader zarejestrowany przez spl_autoload_register() wczytuje plik klasy przy pierwszym jej użyciu. Ten blok zapisuje dwa pliki klas na dysk i wczytuje je automatycznie:

<?php
// Create src/Models/User.php and src/Services/Mailer.php
is_dir('src/Models') || mkdir('src/Models', 0777, true);
is_dir('src/Services') || mkdir('src/Services', 0777, true);
file_put_contents('src/Models/User.php', '<?php
namespace App\Models;
class User { public function __construct(public string $email) {} }
');
file_put_contents('src/Services/Mailer.php', '<?php
namespace App\Services;
use App\Models\User;
class Mailer { public function welcome(User $u): string { return "Welcome mail to {$u->email}"; } }
');

// A minimal PSR-4 autoloader: App\ maps to src/
spl_autoload_register(function (string $class) {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class\n";
    require $file;
});

$mailer = new App\Services\Mailer();
echo $mailer->welcome(new App\Models\User('ada@example.com')), "\n";

Każdy plik klasy jest wczytywany raz, w chwili, gdy klasa jest po raz pierwszy potrzebna. W prawdziwych projektach nie piszesz tej funkcji sam: Composer generuje ją z kilku linii w composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Po composer dump-autoload jedno require __DIR__ . '/vendor/autoload.php'; na początku skryptu wejściowego wczytuje na żądanie każdą klasę App\....

Zasady przestrzeni nazw, które powodują błędy

• namespace musi być pierwszą instrukcją w pliku. Przed nią mogą być tylko declare(strict_types=1); i komentarze.
• Importy use działają w obrębie pliku. Import klasy w index.php nie sprawia, że krótka nazwa działa w dołączonym pliku; każdy plik potrzebuje własnych linii use.
• use należy do najwyższego poziomu pliku lub bloku przestrzeni nazw. W treści klasy use znaczy coś innego: dołącza trait.
• Stringi nigdy nie są rozwiązywane: $class = 'User'; new $class(); szuka globalnego User. Przechowuj pełną nazwę, najlepiej przez User::class.

Ostatnia zasada zasługuje na szybkie sprawdzenie:

<?php
namespace App\Models {
    class User {}
}

namespace App {
    use App\Models\User;

    $short = 'User';
    var_dump(class_exists($short));         // looks for global User
    var_dump(class_exists(User::class));    // App\Models\User

    $class = User::class;
    echo get_class(new $class()), "\n";
}