PHP: Class not found — автозагрузка и Composer autoload

#Как устроена автозагрузка

Composer создаёт файл vendor/autoload.php, который регистрирует автозагрузчик по правилам из composer.json (PSR-4 или classmap). Когда PHP встречает неизвестный класс, он обращается к автозагрузчику, а тот ищет файл по пространству имён. Ошибка Class not found возникает, если: vendor/autoload.php не подключён, пакет не установлен, пространство имён не совпадает с путём к файлу, регистр букв не совпадает (на Linux файловая система чувствительна к регистру), classmap устарел или папка vendor не загружена на сервер.

#Типичные причины

#Порядок

1. Убедитесь, что точка входа подключает автозагрузчик: require __DIR__Это действия разработчика сайта. Откройте проект в редакторе, затем файл входа (часто public/index.php или index.php) и найдите подключение Composer vendor/autoload.php. Путь с __DIR__ считается относительно текущего PHP-файла, поэтому для файла public/index.php обычно нужен require dirname(__DIR__) . '/vendor/autoload.php';, а не __DIR__ . '/vendor/autoload.php'. Сохраните файл после проверки расположения; не добавляйте повторный require в каждый класс.
2. Проверьте, что каталог vendor существует на сервереОткройте терминал в корне проекта (VS Code: «Терминал» → «Создать терминал»). Выполните ls vendor/autoload.php (Linux/macOS) или Test-Path vendor/autoload.php (PowerShell Windows). Если файла нет, значит зависимости не установлены или деплой исключил vendor. Уточните, является ли проект Composer-проектом: рядом должны быть composer.json, обычно composer.lock. Не копируйте чужой каталог vendor из неизвестного источника.
3. Выполните composer installВ корне проекта запустите composer install, если нужен набор зависимостей из composer.lock; для рабочего сервера только после проверки запуска и учёта нужных пакетов разработки обычно используют composer install --no-dev --optimize-autoloader. Сохраните composer.lock и резервную копию перед изменениями. При ошибке проверьте версию PHP, доступность репозитория, права и конкретный пакет по выводу Composer, не заменяйте всё на composer update автоматически.
4. Проверьте правила autoload в composer.jsonВ composer.json откройте раздел autoload → psr-4. Например, запись "App\\": "src/" в JSON означает, что классы App\Services\Mailer должны лежать примерно в src/Services/Mailer.php. Проверьте, что правило зарегистрировано именно в основном autoload, а не только в autoload-dev, если сайт работает с --no-dev. После изменения сохраните валидный JSON и проверьте командой composer validate.
5. Выполните composer dump-autoload -oЕсли менялась конфигурация автозагрузки или переносились файлы классов, из корня проекта выполните composer dump-autoload -o; в консоли должно появиться сообщение о создании файлов автозагрузки. Этот шаг не установит отсутствующий пакет и не исправит опечатку в пространстве имён. Для проверки в терминале PHP можно выполнить php -r 'require "vendor/autoload.php"; var_dump(class_exists("App\Services\Mailer"));', заменив класс своим; bool(true) означает, что автозагрузка его нашла.
6. Сверьте регистр имён файлов и классов и namespaceОткройте файл класса в редакторе и сравните его имя с импортом use или записью new. Для PSR-4 проверьте регистр каждого каталога и файла: Linux различает Mailer.php и mailer.php. В терминале можно выполнить find src -iname '*mailer*' на Linux/macOS; если файла нет в репозитории, проверьте git status и git ls-files. Переименуйте файл с помощью Git, чтобы изменение регистра попало в историю.
7. Проверьте, что файл класса содержит именно этот класс без опечатокВ начале файла класса проверьте объявление namespace и имя class/interface/trait. Например, namespace App\Services; class Mailer соответствует App\Services\Mailer. Убедитесь, что файл не содержит синтаксической ошибки: php -l src/Services/Mailer.php. Если ошибка сообщает о зависимости этого класса, найдите именно вложенный Class not found и исправляйте её отдельно.
8. Проверьте версию PHP: пакет может требовать более новуюВ терминале нужной среды выполните php -v и composer check-platform-reqs (если Composer доступен). Сравните с require и config.platform проекта. На хостинге PHP CLI и PHP-FPM могут использовать разные версии: дополнительно проверьте версию обработчика сайта в панели или phpinfo() на закрытой тестовой странице (не оставляйте её публичной). Если пакет требует другую версию PHP, выбирайте совместимый официальный выпуск, не отключайте проверку требований.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1На рабочем сервере допускается --no-dev лишь если приложение не зависит от dev-пакетов; composer install ме…

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   На рабочем сервере допускается --no-dev лишь если приложение не зависит от dev-пакетов; composer install меняет vendor

   # Из корня проекта, выберите нужный режим установки

   composer install

   composer dump-autoload -o

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

   Вариант 2Пример проверки класса с Composer; PHP-кавычки и реальное имя класса уточнить в проекте

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Пример проверки класса с Composer; PHP-кавычки и реальное имя класса уточнить в проекте

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

   php -r 'require "vendor/autoload.php"; var_dump(class_exists("App\\Services\\Mailer"));'

   Вариант 3Проверить регистр и путь файла

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Проверить регистр и путь файла

   ls -l src/Services/

   find src -iname 'mailer.php'

   Вариант 4Пример настройки PSR-4: пространство имён App\ соответствует каталогу src/

   JSONКомандаКопировать всёВыделить

   Пример настройки PSR-4: пространство имён App\ соответствует каталогу src/

   {

   "autoload": {

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

   }

   }

   Вариант 5Файл класса: путь, имя файла и namespace должны совпадать

   PHPКомандаКопировать всёВыделить

   Файл класса: путь, имя файла и namespace должны совпадать

   <?php

   namespace App\Services;

   class Mailer

   {

   public function send(string $to): bool { return true; }

   }

#Если Composer недоступен на хостинге

Установите зависимости локально (composer install --no-dev), загрузите по FTP каталог vendor целиком вместе с composer.json и composer.lock. Версия PHP локально должна совпадать с версией на хостинге: проверьте composer config platform.php 8.1 для имитации целевой версии.