Пространства имён и автозагрузка в PHP: namespace, use, PSR-4
Пространства имён позволяют использовать одинаковые короткие имена классов в разных частях проекта. Директива use сокращает запись этих имён, а автозагрузчик Composer находит и подключает файлы с объявлениями классов.
Как работает namespace в PHP
namespace задаёт пространство имён для объявленных в файле классов, интерфейсов, трейтов, перечислений, функций и констант. Например, класс Invoice в пространстве App\Billing получает полное имя App\Billing\Invoice. В другом модуле можно объявить App\Archive\Invoice, и PHP будет различать эти классы.
<?php
declare(strict_types=1);
namespace App\Billing;
final class Invoice
{
// Сумма в минимальных единицах валюты.
public function __construct(public readonly int $amount)
{
}
}Объявление namespace ставят в начале файла. Перед ним допустима директива declare(strict_types=1);. HTML, пробелы перед открывающим тегом PHP и BOM в UTF-8 могут вызвать ошибку о том, что объявление пространства имён должно идти первым. В файлах, содержащих только PHP, закрывающий тег обычно опускают.
Сами пространства имён не привязаны к каталогам. Файл с классом App\Billing\Invoice можно подключить вручную с любого пути. Связь между именем класса и расположением файла появляется при настройке автозагрузки, например по PSR-4. Строгая типизация тоже работает отдельно. В частности, режим проверки скалярных аргументов определяется файлом, из которого сделан вызов.
Как использовать use в PHP
use на уровне файла или блока пространства имён создаёт короткое имя для указанного класса. Псевдоним действует в текущем файле или блоке, поэтому его нужно объявить в каждом файле, где он используется. Имена в самих инструкциях use задаются от корня, обычно без начального \.
<?php
declare(strict_types=1);
namespace App\Checkout;
use App\Billing\Invoice as BillingInvoice;
use DateTimeImmutable;
function createInvoice(int $amount): BillingInvoice
{
// Псевдоним ссылается на App\Billing\Invoice.
return new BillingInvoice($amount);
}
function createdAt(): DateTimeImmutable
{
return new DateTimeImmutable('now');
}Без as псевдонимом становится последняя часть имени. Если в одном файле нужны два класса Invoice, задайте одному или обоим разные псевдонимы. Полное имя с начальным \ можно использовать прямо в выражении, например new \App\Billing\Invoice(1500). Импорт пространства use App\Billing; позволяет писать new Billing\Invoice(1500).
Для функций и констант предусмотрены отдельные формы импорта, например use function strlen; и use const PHP_VERSION;. Ключевое слово use внутри класса подключает трейт, а в записи function () use ($amount) передаёт переменную в замыкание.
Как PHP разрешает имена классов, функций и констант
Внутри App\Checkout одно и то же имя может разрешаться по-разному в зависимости от записи и действующих импортов.
| Запись | Какое имя использует PHP |
|---|---|
new Invoice(1500) | App\Checkout\Invoice, если у Invoice нет импорта. |
new Billing\Invoice(1500) | App\Checkout\Billing\Invoice, если Billing не импортирован. |
new \App\Billing\Invoice(1500) | App\Billing\Invoice независимо от импортов. |
new namespace\Invoice(1500) | App\Checkout\Invoice независимо от импортов. |
Для неквалифицированных имён функций и констант действует запасной поиск. Если в App\Checkout нет функции strlen и для этого имени не задан импорт, strlen('abc') вызовет глобальную функцию. Для классов такого перехода нет. Запись new DateTimeImmutable() без импорта ищет класс в текущем пространстве. Глобальный класс доступен через use DateTimeImmutable; или new \DateTimeImmutable().
Импорты применяются к именам в исходном коде. Строка 'BillingInvoice' в динамическом вызове new $class останется короткой строкой. Для такого вызова передайте полное имя или получите его через BillingInvoice::class. Выражение ::class возвращает строку с именем и само по себе не загружает класс. Если нужно проверить, доступен ли класс через автозагрузчик, используйте class_exists(BillingInvoice::class).
PSR-4 в PHP и настройка Composer
PSR — набор рекомендаций по совместимости PHP-проектов. PSR-4 задаёт правила сопоставления пространства имён и пути к файлу. Вы выбираете префикс пространства имён и базовый каталог. Автозагрузчик отбрасывает префикс, превращает оставшиеся части пространства имён в подкаталоги и добавляет .php к имени класса.
Для примера сохраните класс App\Billing\Invoice из первого раздела в src/Billing/Invoice.php. В корне проекта создайте composer.json. В существующем проекте добавьте сопоставление к действующим настройкам autoload.
{
"require": {
"php": "^8.3"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}Ограничение ^8.3 задаёт минимальную версию PHP 8.3 и допускает последующие версии 8.x. Префикс заканчивается обратной косой чертой, которая в JSON записывается как \\. Благодаря завершающей черте префикс App\ соответствует App\Billing\Invoice и не пересекается с Application\. Каталоги Billing и имя файла Invoice.php должны совпадать с соответствующими частями полного имени по регистру. Ошибка в регистре часто проявляется при переносе проекта с Windows на Linux.
Установите зависимости и сгенерируйте файлы автозагрузчика. Если изменили сопоставления в autoload, пересоберите их командой composer dump-autoload.
# Установка зависимостей и создание автозагрузчика.
composer install
# Пересборка после изменения сопоставлений.
composer dump-autoloadПри обычной конфигурации PSR-4 новый класс в уже настроенном каталоге доступен без пересборки. Если сборка использует --classmap-authoritative, Composer ищет классы только по сгенерированной карте. В таком режиме после добавления класса карту нужно обновить. Пространства имён тестов обычно объявляют в autoload-dev, чтобы они не попадали в рабочую сборку с --no-dev.
Подключение vendor/autoload.php и автозагрузка без Composer
Composer создаёт vendor/autoload.php при стандартном расположении каталога зависимостей. Подключите этот файл один раз в точке входа, например в index.php, консольном скрипте или общем файле запуска приложения. Для index.php в корне проекта путь выглядит так.
<?php
declare(strict_types=1);
use App\Billing\Invoice;
// Путь строится от каталога этого файла.
require_once __DIR__ . '/vendor/autoload.php';
$invoice = new Invoice(1500);
echo $invoice->amount, PHP_EOL; // 1500Если точка входа расположена в public/index.php, используйте dirname(__DIR__) . '/vendor/autoload.php'. При обращении к ещё не объявленному классу PHP вызывает зарегистрированные автозагрузчики. Composer вычисляет путь, подключает файл, и PHP получает объявление класса. Сама строка use App\Billing\Invoice; только задаёт имя для последующих выражений.
Автозагрузка классов распространяется также на интерфейсы, трейты и перечисления. Вызов функции и обращение к константе не запускают поиск файлов через PSR-4. Для набора функций, которые должны быть доступны сразу, у Composer есть настройка autoload.files. Указанные там файлы подключаются при инициализации автозагрузчика.
Минимальный автозагрузчик для одного префикса
В небольшом проекте без Composer можно зарегистрировать обработчик через spl_autoload_register(). Этот пример рассчитан на файл запуска в корне проекта и ту же структуру src/Billing/Invoice.php.
<?php
declare(strict_types=1);
spl_autoload_register(static function (string $class): void {
$prefix = 'App\\';
if (!str_starts_with($class, $prefix)) {
return; // Остальные префиксы обработают другие загрузчики.
}
$relative = substr($class, strlen($prefix));
$file = __DIR__ . '/src/' . str_replace('\\', '/', $relative) . '.php';
if (is_file($file)) {
require $file;
}
});
$invoice = new App\Billing\Invoice(1500);
echo $invoice->amount, PHP_EOL;Типичные ошибки и отличия PHP 8.3–8.5
- PHP не открывает
vendor/autoload.php. Проверьте путь относительно__DIR__и наличие каталога зависимостей. В новой копии проекта выполнитеcomposer installиз каталога сcomposer.json. Class ... not found. Сравните полное имя из сообщения сnamespaceи объявлением класса. Проверьте импорт, сопоставление префикса, имя файла и регистр каталогов. При авторитетной карте классов пересоберите её после добавления класса.- PHP сообщает, что имя уже используется. Проверьте, нет ли двух импортов с одним коротким именем или конфликта с именем, объявленным в том же файле. Задайте уникальный псевдоним через
as. - Класс работает в тестах, но пропадает в рабочей сборке. Если он нужен приложению, его сопоставление должно быть в
autoload. Проверьте также, находится ли пакет вrequire, когда сборка выполняется с--no-dev.
В PHP 8.3, 8.4 и 8.5 примеры используют одинаковые правила namespace, use и spl_autoload_register(). PSR-4 реализует автозагрузчик, поэтому смена версии PHP сама по себе не меняет пути к классам. Функция str_starts_with() доступна с PHP 8.0. Магическая функция __autoload() встречается в старом коде и удалена в PHP 8.0. Для замены зарегистрируйте обработчик через spl_autoload_register() или настройте Composer.
При миграции на PHP 8.4 и 8.5 проверьте сигнатуры старых загрузчиков. Начиная с PHP 8.4 запись string $value = null объявляет неявно nullable-параметр и считается устаревшей. Если null действительно допустим, используйте ?string $value = null. Колбэку автозагрузчика PHP передаёт имя класса, поэтому в примере достаточно string $class. Начиная с PHP 8.5 передача false в качестве второго аргумента spl_autoload_register() устарела. Вызов с одним аргументом подходит для всех трёх версий.
Чек-лист настройки автозагрузки
- Объявите пространство имён и поместите класс в файл, соответствующий его полному имени. Для
App\Billing\Invoiceпри префиксеApp\и базеsrc/этоsrc/Billing/Invoice.php. - Добавьте префикс в
autoload.psr-4файлаcomposer.json. Выполнитеcomposer installв новой копии проекта илиcomposer dump-autoloadпосле правки сопоставлений. - Подключите
vendor/autoload.phpв каждой точке входа или в общем файле запуска. Проверьте путь от каталога файла. - Импортируйте классы через
use, если нужны короткие имена. Для динамических вызовов передавайте имя, полученное через::class. - Запустите приложение через штатную точку входа. Если класс не найден, начните с полного имени в ошибке, затем сверьте префикс, путь, регистр и режим генерации карты классов.
Частые вопросы
Чем namespace отличается от use в PHP?
namespace определяет пространство имён для объявлений в файле, а use создаёт локальный псевдоним для имени из другого пространства. Подключение файла при обращении к классу выполняет автозагрузчик.
Где взять vendor/autoload.php?
В стандартной конфигурации Composer создаёт этот файл в каталоге vendor. Выполните composer install из каталога с composer.json и подключите файл в точке входа по пути относительно __DIR__.
Нужно ли запускать composer dump-autoload после добавления класса?
В обычном режиме PSR-4 новый класс под уже настроенным префиксом доступен сразу, если путь и регистр совпадают. Пересборка нужна после изменения сопоставлений и после добавления классов в сборку с авторитетной картой.