PHPTime

Пространства имён и автозагрузка в PHP: namespace, use, PSR-4

Пространства имён позволяют использовать одинаковые короткие имена классов в разных частях проекта. Директива use сокращает запись этих имён, а автозагрузчик Composer находит и подключает файлы с объявлениями классов.

Как работает namespace в PHP

namespace задаёт пространство имён для объявленных в файле классов, интерфейсов, трейтов, перечислений, функций и констант. Например, класс Invoice в пространстве App\Billing получает полное имя App\Billing\Invoice. В другом модуле можно объявить App\Archive\Invoice, и PHP будет различать эти классы.

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
<?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.

JSON
{
  "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.

Shell
# Установка зависимостей и создание автозагрузчика.
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
<?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
<?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() устарела. Вызов с одним аргументом подходит для всех трёх версий.

Чек-лист настройки автозагрузки

  1. Объявите пространство имён и поместите класс в файл, соответствующий его полному имени. Для App\Billing\Invoice при префиксе App\ и базе src/ это src/Billing/Invoice.php.
  2. Добавьте префикс в autoload.psr-4 файла composer.json. Выполните composer install в новой копии проекта или composer dump-autoload после правки сопоставлений.
  3. Подключите vendor/autoload.php в каждой точке входа или в общем файле запуска. Проверьте путь от каталога файла.
  4. Импортируйте классы через use, если нужны короткие имена. Для динамических вызовов передавайте имя, полученное через ::class.
  5. Запустите приложение через штатную точку входа. Если класс не найден, начните с полного имени в ошибке, затем сверьте префикс, путь, регистр и режим генерации карты классов.

Частые вопросы

Чем namespace отличается от use в PHP?

namespace определяет пространство имён для объявлений в файле, а use создаёт локальный псевдоним для имени из другого пространства. Подключение файла при обращении к классу выполняет автозагрузчик.

Где взять vendor/autoload.php?

В стандартной конфигурации Composer создаёт этот файл в каталоге vendor. Выполните composer install из каталога с composer.json и подключите файл в точке входа по пути относительно __DIR__.

Нужно ли запускать composer dump-autoload после добавления класса?

В обычном режиме PSR-4 новый класс под уже настроенным префиксом доступен сразу, если путь и регистр совпадают. Пересборка нужна после изменения сопоставлений и после добавления классов в сборку с авторитетной картой.

Справка по теме

Ещё в разделе «Справочник PHP»

Работа с файлами в PHP: чтение, запись, удаление

Как читать, записывать, копировать и удалять файлы в PHP 8.3–8.5. Рабочие примеры с file_get_contents, file_put_contents, fopen, filesize и unlink.

11 мин

Регулярные выражения в PHP: preg_match, preg_replace и шаблоны

Как составлять регулярные выражения в PHP, искать совпадения через preg_match, заменять текст через preg_replace и учитывать Unicode и различия PHP 8.3–8.5.

8 мин

Редирект в PHP: header Location, коды 301 и 302

Как сделать редирект в PHP через header Location, выбрать между 301, 302, 303, 307 и 308, обработать POST и исправить ошибку headers already sent.

9 мин

Сессии в PHP: session_start, хранение данных и безопасность

Как запустить сессию в PHP через session_start, хранить данные в $_SESSION, настроить cookie, сменить идентификатор при входе и завершить сессию.

8 мин