Пространства имён PHP: namespace, use и псевдонимы

Пространство имён PHP помещает классы, функции и константы под префикс, чтобы их имена не сталкивались с чужими. Его объявляют через namespace App\Models; первой инструкцией файла, а другие файлы обращаются к классу как \App\Models\User или импортируют его через use App\Models\User; и пишут просто 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";

Внутри пространства имён User означает App\Models\User. User::class даёт полное имя строкой, ничего не создавая, что удобно для логирования и для автозагрузчиков.

Два пространства имён в одном файле

В реальном проекте в каждом файле одно пространство имён. Для самостоятельной демонстрации в одном файле может быть несколько пространств имён, если каждое обёрнуто в фигурные скобки. Код, который не относится ни к одному пространству имён, помещается в 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";
}

Два класса с именем Order живут рядом, потому что их полные имена различаются. Именно эту проблему решают пространства имён, когда вы устанавливаете библиотеки: ваш Order, Order платёжной библиотеки и Order библиотеки для PDF больше не конфликтуют.

Импорт через use и псевдоним через as

Писать везде \Shop\Order громоздко. use в начале файла (или блока пространства имён) импортирует имя, чтобы можно было использовать короткую форму. Когда два импорта заканчиваются на одно и то же короткое имя, as даёт одному из них другое имя:

<?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 лишь создаёт короткое имя до конца файла. Он не загружает файл и не выполняет код и работает одинаково, существует класс или ещё нет. Допускаются и групповые импорты: use Shop\{Order, Invoice};.

use function и use const

Функции и константы из пространства имён импортируются через use function и 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";
}

Глобальным классам нужен обратный слеш

Внутри пространства имён неквалифицированное имя класса разрешается относительно этого пространства, поэтому new DateTime() внутри namespace App; ищет App\DateTime. С функциями и константами иначе: если App\strlen не существует, PHP откатывается к глобальной strlen. Классы никогда не откатываются.

<?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) обратный слеш понадобился по той же причине: без него PHP искал бы App\Error, никогда не совпал бы с настоящей ошибкой, и скрипт остановился бы с неперехваченным Error. Исправьте это начальным обратным слешем, как выше, или через use DateTime; в начале файла. То же касается \Exception, \Throwable и любого другого встроенного класса; как их перехватывать, смотрите в try catch.

Автозагрузка и PSR-4

В проекте каждый класс лежит в своём файле, а путь к файлу следует пространству имён. PSR-4 это соглашение: префикс пространства имён сопоставляется базовой папке, а остаток имени становится путём. Автозагрузчик, зарегистрированный через spl_autoload_register(), загружает файл класса при первом использовании класса. Этот блок записывает на диск два файла классов и загружает их автоматически:

<?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";

Каждый файл класса загружается один раз, в тот момент, когда класс впервые нужен. В реальных проектах эту функцию сами не пишут: её генерирует Composer по нескольким строкам в composer.json:

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

После composer dump-autoload одна строка require __DIR__ . '/vendor/autoload.php'; в начале входного скрипта загружает любой класс App\... по требованию.

Правила пространств имён, которые приводят к ошибкам

• namespace должен быть первой инструкцией в файле. Перед ним могут стоять только declare(strict_types=1); и комментарии.
• Импорты use действуют в пределах файла. Импорт класса в index.php не делает короткое имя рабочим внутри подключённого файла; каждому файлу нужны свои строки use.
• use ставится на верхнем уровне файла или блока пространства имён. Внутри тела класса use означает другое: он подключает трейт.
• Строки никогда не разрешаются: $class = 'User'; new $class(); ищет глобальный User. Храните полное имя, лучше всего через User::class.

Последнее правило стоит быстро проверить:

<?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";
}