Пространства имён в PHP: чек-лист перед продакшеном

Класс работает на вашей машине и выдаёт Fatal error: Uncaught Error: Class "App\Service\Payment" not found на продакшене. Причина почти всегда одна: несоответствие между пространством имён, физическим путём файла и тем, что прописано в composer.json. На macOS и Windows файловая система нечувствительна к регистру, на большинстве Linux-серверов — чувствительна. Ниже — чек-лист для PHP 8.x и Composer 2.x, который ловит эти проблемы до того, как их найдёт пользователь.

Почему namespace ломается именно в проде, а не локально

Пространство имён в PHP — это логическая метка внутри файла, объявленная строкой namespace App\Service;. Оно никак не связано с расположением файла на диске напрямую. Связь создаёт автозагрузчик: PSR-4¹ договаривается, что префиксу App\ соответствует папка src/, а дальше сегменты namespace один в один ложатся на подпапки, а имя класса — на имя файла.

Пока файловая система прощает регистр, ошибка «имя класса Payment, а файл payment.php» невидима. На Linux-сервере с ext4 или xfs эта же строка выбросит fatal error. То же с лишними или недостающими сегментами namespace: локально Composer нередко работает через authoritative classmap из кеша и находит класс по старой карте, а на чистом сервере — уже нет.

Разница между dev и prod почти всегда в трёх вещах: регистр символов, содержимое папки vendor и наличие оптимизированной карты классов. Всё остальное — производные.

Чек-лист: что проверить перед деплоем

1. Регистр namespace и имени файла совпадают посимвольно. Класс App\Service\PaymentGateway обязан лежать в src/Service/PaymentGateway.php. Не service, не paymentgateway.php. Проверка: команда ниже находит расхождения без деплоя.
2. Блок autoload.psr-4 в composer.json покрывает все ваши префиксы. Каждому корневому namespace соответствует ровно одна папка (или несколько через массив), и путь заканчивается слэшем.
3. Собрана оптимизированная карта классов. Без неё автозагрузчик на каждый неизвестный класс лезет в файловую систему, что и по скорости плохо, и маскирует часть ошибок.
4. Нет ручных require вперемешку с автозагрузкой. Двойное подключение файла с объявлением класса даёт Cannot declare class, already declared.
5. Импорты use указывают на существующие классы. Опечатка в use App\Modle\User; не видна до момента обращения к классу.
6. Папка vendor собрана на том же мажоре PHP, что и прод. Расхождение версий в platform ломает часть зависимостей молча.

Как найти расхождения регистра до деплоя

Первое, что стоит запустить, — валидацию манифеста и проверку автозагрузки в строгом режиме. Composer 2.x умеет отдельно проверять, что все классы из ваших PSR-4 путей реально резолвятся:

# проверяем корректность composer.json
composer validate --strict

# собираем карту классов и предупреждаем о нарушениях PSR-4
composer dump-autoload --optimize --strict-psr

Флаг --strict-psr заставляет Composer вывести список классов, чьё имя или расположение не соответствует правилам PSR-4, — включая несовпадение регистра. Именно это чаще всего и стреляет на Linux. Если команда завершилась без предупреждений, регистр и структура папок в порядке. Точное поведение флагов сверяйте с документацией вашей версии Composer — набор опций между 2.x-минорами дополнялся.

Оптимизация автозагрузки для прода

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

# карта классов + запрет поиска мимо карты
composer install --no-dev --optimize-autoloader --classmap-authoritative

Флаг --classmap-authoritative означает: если класса нет в карте — считать, что его нет вообще, не проверяя диск. Это ускоряет автозагрузку, но у него есть цена — см. раздел про подводные камни. Флаг --no-dev выкидывает dev-зависимости, чтобы на проде не оказалось PHPUnit и отладочных пакетов.

Частые ошибки и что делать

• Class "App\Service\X" not found, а файл на месте. Сравните посимвольно namespace в шапке файла, путь к файлу и префикс в composer.json. Затем пересоберите карту: composer dump-autoload -o. На локали проверяйте регистр вручную — файловая система его прощает, а прод нет.
• Класс работал, после добавления нового — not found. С включённым classmap-authoritative новые классы не попадают в карту без пересборки. После каждого деплоя нужен composer dump-autoload -o либо полный composer install.
• Cannot redeclare class. Где-то остался ручной require или include на файл, который уже подхватывает автозагрузчик. Уберите ручное подключение.
• Класс из глобального пространства не находится внутри namespace. Внутри файла с namespace App; обращение к DateTime ищет App\DateTime. Пишите \DateTime или добавьте use DateTime;.
• composer validate ругается на устаревший lock. Файл composer.lock не соответствует composer.json. Обновите зависимости на dev-машине и закоммитьте оба файла — на прод они едут вместе.

Подводные камни classmap-authoritative в проде

Авторитетная карта классов — самый частый источник инцидентов «вчера работало, сегодня 500». Механика простая: PHP держит карту в памяти через OPcache, и пока карта не пересобрана, автозагрузчик буквально не видит новые файлы, даже если они физически лежат в проекте.

Отдельный слой проблемы — сам OPcache. Даже пересобранная карта не подхватится, если PHP-FPM закешировал старую версию файла автозагрузчика. Здесь помогают два подхода:

Если релизы редкие и вы не готовы автоматизировать пересборку карты, безопаснее использовать --optimize-autoloader без --classmap-authoritative: карта ускоряет известные классы, но для отсутствующих в ней автозагрузчик всё же проверит диск. Вы теряете часть выигрыша по скорости, но не получаете «невидимых» новых классов.

Правило для CI: composer dump-autoload -o --strict-psr в пайплайне — дешёвый предохранитель. Он падает на регистре и структуре папок до того, как это увидит прод.

Что делать дальше

Добавьте composer validate --strict и composer dump-autoload -o --strict-psr отдельным шагом в CI до сборки образа — тогда несовпадение регистра свалит пайплайн, а не продакшен. В скрипт деплоя пропишите пересборку карты и reload PHP-FPM после переключения релиза. На проде мониторьте частоту fatal-ошибок с текстом Class not found — их всплеск после релиза почти всегда указывает на непересобранную карту или незасквоженный OPcache. За точным набором флагов вашей версии Composer идите в официальную документацию раздела autoloading: набор опций между минорами 2.x менялся.