Как разбирать ошибку 500 в Yii2-проекте

Ошибка 500 выглядит одинаково для пользователя: сайт не открылся, форма не отправилась, админка показала белый экран. Но внутри причин может быть много: ошибка PHP, проблема с правами, неверный конфиг, недоступная база, сломанная миграция, старый кэш или конфликт после обновления зависимостей.

Разбирать такую ошибку лучше спокойно и по порядку. Не нужно сразу менять код или перезапускать всё подряд. Сначала важно найти место, где появилась конкретная ошибка.

Проверить, где именно возникает 500

Для начала стоит понять масштаб проблемы. Не открывается весь сайт или только один раздел? Ошибка появляется для всех пользователей или только после отправки формы? Работает ли консольная команда?

• открыть главную страницу;
• открыть проблемный URL напрямую;
• проверить админку;
• повторить действие, после которого возникает ошибка;
• сравнить поведение в обычном режиме и без авторизации.

Если падает только одна страница, круг поиска уже меньше. Если не работает весь проект, стоит смотреть конфиг, зависимости, базу, права и веб-сервер.

Лог Yii2

В Yii2 первая точка проверки — runtime/logs/app.log. Даже если на экране ничего полезного нет, в логе часто лежит точное исключение с файлом и строкой.

tail -n 150 runtime/logs/app.log

Если ошибка свежая, удобнее смотреть лог в момент повторения действия:

tail -f runtime/logs/app.log

Типовые сообщения, которые быстро указывают направление:

• Class not found — проблема с зависимостями, namespace или autoload;
• Unknown Property — код обращается к несуществующему свойству;
• SQLSTATE — ошибка базы данных или запроса;
• Permission denied — права на файл или директорию;
• Invalid Configuration — проблема в конфиге приложения.

Логи nginx и PHP-FPM

Если в логе Yii2 пусто, ошибка может возникать раньше запуска приложения. Тогда нужно смотреть веб-сервер и PHP-FPM.

tail -n 150 /var/log/nginx/error.log
tail -n 150 /var/log/php-fpm/error.log

Пути к логам отличаются в зависимости от сервера. На shared-хостинге они могут быть в панели управления или в отдельной папке logs рядом с сайтом.

Проверка синтаксиса PHP

После ручной правки файла или неудачного merge часто бывает обычная синтаксическая ошибка. Если проект небольшой, можно быстро проверить все PHP-файлы, исключив vendor.

find . -name "*.php" -not -path "./vendor/*" -print0 | xargs -0 -n1 php -l

Если ошибка появилась после выкладки конкретного коммита, лучше проверить только изменённые файлы. Это быстрее и меньше шумит.

git diff --name-only HEAD~1 HEAD | grep ".php$" | xargs -n1 php -l

Права на runtime и assets

Yii2 должен писать в runtime, а web/assets используется для опубликованных ресурсов. Если права сломались, сайт может падать даже без изменения бизнес-логики.

ls -la
ls -la runtime
ls -la web/assets

Обычно достаточно выдать права пользователю веб-сервера. Имя пользователя зависит от окружения: www-data, nginx, apache или пользователь хостинга.

chown -R www-data:www-data runtime web/assets
chmod -R ug+rw runtime web/assets

Ставить 777 на всё дерево проекта не стоит. Это маскирует проблему и создаёт новую.

Конфиги и переменные окружения

Ошибка 500 после переноса сайта часто связана с локальными конфигами. Например, указан старый пароль базы, неправильный host Redis, включён file transport для почты или отсутствует секретный ключ.

php yii help

Если даже консольная команда Yii2 не запускается, проблема почти точно в конфигурации, зависимостях или синтаксисе. Если консоль работает, а сайт нет, нужно смотреть nginx, PHP-FPM, document root и права.

База данных

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

php yii migrate/history
php yii migrate --interactive=0

Если миграции выполнять нельзя без проверки, сначала стоит посмотреть список новых миграций:

php yii migrate/new

Кэш

После обновления конфигов, зависимостей или структуры таблиц может мешать старый кэш. Особенно если включён schema cache или файловый кэш.

php yii cache/flush-all

Если консоль не работает, можно аккуратно очистить файловый кэш вручную. Удалять нужно содержимое, а не сами рабочие директории.

rm -rf runtime/cache/*

Короткий порядок диагностики

1. Повторить ошибку и понять, где она возникает.
2. Открыть runtime/logs/app.log.
3. Проверить nginx и PHP-FPM error log.
4. Проверить синтаксис изменённых PHP-файлов.
5. Проверить права на runtime и web/assets.
6. Проверить подключение к базе и миграции.
7. Очистить кэш, если причина похожа на старые данные.
8. После исправления ещё раз посмотреть свежие логи.

Ошибка 500 неприятна тем, что пользователь видит только общий сбой. Но для разработчика это не диагноз, а входная точка. Почти всегда конкретная причина уже записана в одном из логов, и задача — не угадать её, а аккуратно найти.