PHP на сервере LinuxPHP 8.x

PHP Class not found из-за регистра имени файла в Linux

  • Обновлено
  • Чтение ≈ 4 минуты

Краткий ответ

В Linux имена UserService.php и userservice.php обычно различаются, поэтому проект, работавший на файловой системе без учёта регистра, может ломаться только после переноса на сервер.

В этой статье
  1. Симптомы, область применения и причины
  2. Безопасная диагностика и пошаговое исправление
  3. Как проверить результат и что делать дальше

#Симптомы, область применения и причины

После переноса PHP-проекта с Windows на Linux автозагрузка не находит класс из-за разницы между именем PHP-файла, пространством имён и путём автозагрузчика Composer. В Linux имена UserService.php и userservice.php обычно различаются, поэтому проект, работавший на файловой системе без учёта регистра, может ломаться только после переноса на сервер.

Возможная причинаКак узнатьЧто делать
Регистр символов пути не совпадаетВ src/Service/UserService.php и ожидаемом пути автозагрузчика используются разные заглавные буквы.На Windows работает, а на Linux возникает Class ... not found.Сопоставить полный путь в автозагрузчике PSR-4 и точное имя файла.
Неверное пространство имён или сопоставление PSR-4Класс указан в одном namespace, а файл находится в другом каталоге.Ошибка сохраняется и при правильном регистре basename.Проверить namespace, use и раздел autoload composer.json.
Автозагрузчик/кеш использует старую картуПосле смены имени файла Composer ещё хранит прежний путь.Переименование уже выполнено, но Class not found сохраняется только в развёрнутой сборке.Выполнить штатное обновление карты загрузки на стороне проекта.

#Безопасная диагностика и пошаговое исправление

  1. Запишите имя отсутствующего класса целикомВ панели сайта откройте журнал PHP и найдите исходное сообщение Class "Vendor\Package\Name" not found или ошибку require с указанным путём. Скопируйте полное пространство имён вместе с регистром букв, а также время и исходный обработчик запроса. Не скачивайте библиотеку с неизвестного сайта: её файл может уже существовать под другим именем.
  1. Найдите файл и сравните каждую буквуОткройте файловый менеджер панели или редактор проекта на сервере, перейдите от корня проекта к каталогу src/app по структуре вашего приложения. Найдите файл класса и проверьте совпадение прописных/строчных букв имени, каталогов и расширения .php. Например, запрос App\Service\MailSender при PSR-4 App\ → src/ предполагает файл src/Service/MailSender.php. Linux сравнивает регистр имени каждого каталога, а не только файла.
  1. Сопоставьте namespace в самом файлеОткройте найденный PHP-файл и прочитайте строку namespace и объявление class. Для примера namespace App\Service; class MailSender должно соответствовать вызову App\Service\MailSender и сопоставлению PSR-4. Не переименовывайте сам класс без поиска всех его обращений; сначала исправьте точную ошибку пути и сохраните копию.
  2. Пример кода по теме
    PHP
    Учебный пример расположения класса в src/Service/MailSender.php, если в Composer задано PSR-4 App\ → src/.
    <?php
namespace App\Service;
final class MailSender {}
  1. Проверьте Composer-конфигурациюВ корне проекта откройте composer.json, найдите autoload → psr-4; сопоставьте префикс, путь к каталогу и регистр. Если проекта без Composer, найдите свой spl_autoload_register и посмотрите фактические правила построения имени файла. Убедитесь, что на веб-сервере установлены те же исходники, что и у разработчика; перед правками создайте резервную копию файла и сохраните текущую версию проекта.
  1. Исправьте путь с учётом контроля версийПереименуйте файл и каталоги так, чтобы они точно соответствовали классу и PSR-4. Если разработка ведётся на Windows и Git не замечает смену только регистра, выполните временное переименование в другое имя и затем в нужное с фиксацией изменений в Git; не переименовывайте массу файлов автоматически. В Linux убедитесь, что новый путь находится в той же точке, которую ожидает автозагрузчик.
  1. Обновите карту автозагрузки штатноЕсли проект использует Composer, из терминала в корне проекта (там, где composer.json) выполните composer dump-autoload -o, предварительно убедившись, что Composer установлен и в сборке нет несогласованных изменений. Ключ -o создаёт оптимизированную карту классов; команда не ставит новые пакеты и не заменяет composer.lock. На сервере с управляемым выпуском лучше обновить карту во время сборки, а не вручную в рабочем каталоге.
    Linux · Терминал (Bash)Команда
    В корневом каталоге PHP-проекта, в среде с установленным Composer. Обычных прав владельца проекта достаточно.
    composer dump-autoload -o
  1. Очистите только соответствующий кеш приложения при необходимостиЕсли Composer пересобран, но всё ещё загружается прежний путь, проверьте механизм кеша фреймворка и Opcache. Перезапуск пула PHP-FPM допустим только после проверки состояния и в плановом окне, если именно Opcache сохраняет старый код; не отключайте Opcache для всех сайтов. Если сообщение изменилось на ошибку метода или зависимостей, это уже другая неисправность.
  1. Проверьте исправленный путь и выполните откат при неуспехеВ тестовой среде загрузите страницу, которая ранее приводила к Class not found; сравните журнал и загрузку класса. Затем убедитесь, что другие маршруты сайта работают. Если ошибка остаётся, верните исходный файл из копии, восстановите карту Composer предыдущего выпуска и передайте разработчику имя класса, путь, PSR-4-префикс и точный текст ошибки.

#Как проверить результат и что делать дальше

Показатель успеха — нужный класс подгружается на Linux без обходов и не возникает новых ошибок автозагрузки на соседних маршрутах. Если проблема воспроизводится, сравните содержимое файлов и регистрацию классов, не применяйте глобальное переименование путей или ослабление прав каталогов.

Так эту ошибку тоже называют

PHP Parse error: syntax error, unexpected T_STRING — причины и решение Найдите пропущенную точку с запятой, скобку или кавычку в указанной строке. Сайты, серверы и хостинг PHP на сервере Linux Allowed memory size PHP Fatal error: Allowed memory size exhausted — причины и решение `Fatal error: Allowed memory size of N bytes exhausted (tried to allocate M bytes)` означает, что PHP-скрипт превысил лимит памяти, заданный `memory_limit`. Причина — ли… Сайты, серверы и хостинг PHP на сервере PHPWordPressLinux PHP: Warning: Undefined variable / Undefined array key — причины и решение Предупреждения возникают при обращении к необъявленной переменной или несуществующему ключу массива. Проверяйте isset(), ?? и инициализируйте переменные. Сайты, серверы и хостинг PHP на сервере LinuxWindows PHP: Call to undefined function mb_strlen() — не установлено расширение mbstring — причины и решение «Call to undefined function mb_strlen()» в PHP означает, что не установлено или не включено расширение mbstring. Установите пакет phpX.Y-mbstring, раскомментируйте exten… Сайты, серверы и хостинг PHP на сервере LinuxWindows PHP: Cannot modify header information — headers already sent — причины и решение «Cannot modify header information — headers already sent» в PHP возникает, когда вывод начался раньше вызова header(), setcookie() или session_start(). Найдите место выв… Сайты, серверы и хостинг PHP на сервере LinuxWindows

Источники и обновления

Последнее обновление статьи: 2 ноября 2026. Версии программ и интерфейсы меняются — если шаги не совпадают с вашей версией, сверяйтесь с документацией производителя.