Как найти причину ошибки на PHP: версия, логи и шаги воспроизведения
Ошибка на PHP редко бывает «магической»: у неё есть тип, место, контекст и условие появления. Как найти причину ошибки на PHP, если сайт уже отдаёт 500, а на экране только белая страница? Начните с фиксации версии и окружения, затем доберитесь до логов, после чего соберите минимальные шаги воспроизведения. Такой порядок помогает не гадать, а сужать круг гипотез.
Как найти причину ошибки на PHP: начните с версии и окружения
Первое, что стоит сделать, — понять, где именно выполняется код. Ошибка может появляться в CLI-скрипте, в PHP-FPM под веб-сервером, в контейнере или на другом сервере. Номер версии PHP, набор расширений и способ запуска влияют на то, какие функции доступны, как обрабатываются типы и какие предупреждения попадают в лог.
Не сравнивайте «примерно одинаковые» окружения. Зафиксируйте точные данные: версию PHP, SAPI, версию зависимостей, ОС, переменные окружения и коммит кода. Если проект только выбирает стек, полезно заранее сравнить направления Python и PHP, но для разбора уже случившейся ошибки важнее не выбор языка, а совпадение среды.
- версия PHP и способ запуска: CLI, PHP-FPM, модуль веб-сервера;
- версия зависимостей из composer.lock и наличие нужных расширений;
- операционная система, контейнер или хостинговая среда;
- переменные окружения и файлы конфигурации, которые различаются между стендами;
- версия кода или коммит, на котором воспроизводится проблема.
Если приложение развёрнуто в нескольких средах, полезно составить короткую карточку окружения: версия PHP, SAPI, расширения, версия базы, параметры памяти и таймаутов. Она помогает быстро заметить расхождение. Не полагайтесь на память и не сравнивайте только название хостинга.
Почему версия PHP меняет поведение
При переходе между мажорными версиями часть возможностей может помечаться устаревшей, а часть синтаксиса — становиться недоступной. Даже если код не менялся, на новом сервере он может вести себя иначе. Поэтому сообщение «у меня локально работает» само по себе не отменяет проверку версии: сравните вывод php -v на обоих стендах и убедитесь, что код запускается тем же способом.
Отдельно проверьте, какой файл конфигурации читает PHP. В CLI и в веб-режиме это могут быть разные php.ini. Если используется контейнер, сверьте образ и переменные сборки. Если зависимости ставятся через Composer, проверьте, не требует ли пакет другую платформу. Такие детали помогают объяснить ошибку, которая не повторяется на машине разработчика.
Где посмотреть версию без догадок
В CLI версию показывает php -v, сведения о расширениях — php -m, а полную конфигурацию — php -i. На сервере можно временно вывести phpinfo() на закрытом стенде, но не стоит оставлять такую страницу публично доступной. Если доступ к настройкам есть через панель хостинга, сверьтесь с ней и с конфигурацией веб-сервера.
php.ini. Два сайта с одинаковым PHP могут читать разные конфигурации.Включите логирование и найдите источник сообщения
Браузер не является надёжным местом для диагностики. На боевом сервере сообщения об ошибках могут быть скрыты, а на локальном — наоборот, включены не полностью. Для разбора нужна пара инструментов: вывод ошибок на локальной машине и запись в лог на сервере.
error_reportingдолжен включать нужные уровни, на время диагностики —E_ALL;display_errorsудобно включать локально, но не на публичном сервере;log_errorsвключает запись ошибок в журнал;- путь в
error_logдолжен быть доступен для записи; - журнал веб-сервера стоит смотреть отдельно от журнала PHP;
- в приложении может быть свой логгер, который перехватывает исключения.
На локальной машине удобно держать вывод ошибок включённым, но на сервере — писать в файл. Если вы видите ошибку только в браузере, скопируйте её текст, время и URL, а затем найдите ту же запись в журнале. Это поможет понять, не искажает ли сообщение промежуточный обработчик.
Три слоя логов: PHP, веб-сервер, приложение
Сообщение об ошибке PHP может попасть в журнал PHP, в журнал веб-сервера или в лог приложения. Это разные слои. Если на экране пустая страница, начните с журнала веб-сервера: там может быть код ответа и запись о том, что запрос не дошёл до приложения. Затем проверьте журнал PHP и лог фреймворка. В приложении ищите идентификатор запроса, если он используется.
Полезно сразу выписать время ошибки, URL или команду, тип запроса и идентификатор пользователя, если он есть в логах. Не копируйте в публичные отчёты пароли, токены и персональные данные: для диагностики достаточно обезличенного фрагмента.
Если журнал пуст, проверьте, куда именно настроена запись. В одних средах ошибки уходят в stderr и попадают в журнал веб-сервера, в других — в отдельный файл. Иногда приложение перехватывает ошибку и показывает собственное сообщение, а исходная причина остаётся только во внутреннем логе. Ищите запись по времени и тексту исключения, а не только по слову «error».
Прочитайте ошибку и stack trace
Сообщение об ошибке состоит не только из текста. Смотрите на тип, файл, строку и цепочку вызовов. Фатальная ошибка останавливает выполнение, предупреждение может продолжать работу, а исключение несёт stack trace. В трассировке важно найти первый кадр, который относится к вашему коду, а не к библиотеке или фреймворку.
- тип ошибки: предупреждение, фатальная ошибка или исключение;
- файл и строка, где возникла проблема;
- первый кадр stack trace, относящийся к вашему коду;
- предыдущее исключение, если оно есть;
- входные данные и состояние, при которых это произошло.
Если в сообщении есть предыдущее исключение, читайте его тоже: причина может быть в нём, а верхняя ошибка — только следствие. Если лог обрезан, проверьте настройки ротации и лимиты. Если трассировка многострочная, сохраняйте её целиком: по одной строке легко потерять контекст.
Не путайте место, где проявилась ошибка, с местом, где она возникла. Строка в шаблоне может быть лишь последним звеном. Если ошибка возникла в библиотеке, проверьте, какие данные вы передали в её метод. Если в ядре фреймворка — посмотрите, какое исключение было раньше.
Представим ситуацию: в шаблоне появляется ошибка о неопределённой переменной. Сама строка указывает на шаблон, но причина может быть в контроллере, который не передал данные, или в ветке кода, которая выполнилась только при определённом запросе. Поэтому от места ошибки полезно пройти назад по цепочке вызовов и проверить, какие данные должны были туда попасть.
Соберите шаги воспроизведения
Без воспроизведения трудно понять, что именно исправлять. Хорошие шаги воспроизведения не требуют доступа к вашей голове: это конкретная последовательность действий, входные данные и ожидаемый результат. Для интеграций и API полезно заранее описать контракт: входные данные, ошибки и повтор запросов. Тогда причина ошибки видна не только в коде, но и в несоответствии ожиданий.
- Укажите точку входа: URL, команду, задачу планировщика или вызов метода.
- Опишите входные данные без секретов: тип запроса, параметры, пример полезной нагрузки.
- Перечислите последовательность действий до ошибки.
- Зафиксируйте ожидаемый и фактический результат.
- Добавьте версию PHP, окружение и версию кода.
- Приложите короткий фрагмент лога с временем и stack trace.
Если ошибка плавающая, шаги могут быть неполными. Тогда ищите корреляцию по времени, идентификатору запроса, объёму данных, параллельным запросам и состоянию внешних сервисов. Не делайте вывод по одному случаю: проверьте, повторяется ли сценарий при тех же условиях.
Для фоновых задач добавьте в описание запуск вручную и расписание. Для API — метод, заголовки, тело запроса и код ответа. Для форм — какие поля заполнены и какие проверки сработали. Чем точнее сценарий, тем быстрее можно отделить ошибку данных от ошибки конфигурации или кода.
Сузьте круг гипотез: данные, конфигурация, код
После сбора фактов меняйте по одной переменной за раз. Сначала проверьте данные: пустые значения, кодировку, формат даты, неожиданно длинную строку. Затем конфигурацию: права на файлы, лимиты памяти, таймауты, доступ к каталогу, настройки расширений. После этого — код: недавние изменения, граничные условия, обработку исключений.
Полезно проверить, не маскирует ли приложение исходную ошибку. Например, общий обработчик может показывать «что-то пошло не так», хотя в логе есть конкретное исключение. Если ошибка связана с внешним сервисом, отделите проблему сети или ответа от проблемы разбора данных. Если с базой данных — проверьте запрос, параметры и соединение, но не подменяйте диагностику догадками.
Отдельно проверьте пути и права. Ошибка может выглядеть как проблема кода, но возникать из-за недоступного каталога, файла или кеша. Сравните владельца файлов и права на запись. Если приложение использует временные файлы, убедитесь, что каталог существует и доступен процессу PHP.
Когда гипотез много, помогает бинарное сужение: отключите часть кода, замените входные данные на минимальные, запустите тот же сценарий на чистом окружении. Цель — не «починить всё сразу», а найти наименьшее условие, при котором ошибка исчезает или появляется.
Проверьте также, не изменилось ли окружение вокруг кода: обновление зависимости, новая версия PHP, другой часовой пояс, права доступа или лимиты. Если ошибка появилась после обновления, сравните поведение на предыдущей версии. Если сбой был и раньше, проверьте, не изменились ли данные или конфигурация.
Проверьте исправление и не потеряйте контекст
После исправления повторите исходные шаги воспроизведения. Если ошибка исчезла, проверьте соседние сценарии: пустые данные, неверный формат, повторный запрос, другое окружение. Для повторяющейся проблемы добавьте тест или хотя бы сохраните минимальный пример в задаче. Так причина не потеряется при следующем изменении кода.
Уберите временную диагностику: выключите публичный вывод ошибок, проверьте уровень логирования и не оставляйте отладочные страницы доступными. В задаче или changelog зафиксируйте, что было причиной, какие логи помогли и какие условия нужно проверять снова. Это экономит время при похожем сбое.
Если ошибка была связана с версией PHP или зависимостью, запишите точные версии и способ воспроизведения. Если с данными — сохраните обезличенный пример. Если с конфигурацией — отметьте, какой параметр изменился. Такой контекст полезнее, чем короткая запись «исправлено».
Если проблема была в версии, зафиксируйте её в требованиях проекта. Если в зависимости — проверьте lock-файл и обновите описание сборки. Если в коде — добавьте тест, который повторяет минимальный сценарий. Это не гарантирует отсутствие других ошибок, но сохраняет найденную причину.
С чего начать, если на экране только белая страница?
Сначала посмотрите журнал веб-сервера и журнал PHP: там может быть код ответа, текст ошибки или запись о падении процесса. Если доступа к логам нет, включите диагностику на локальном или тестовом стенде и повторите сценарий. Публично выводить ошибки на боевом сайте не стоит.
Почему локально ошибки нет, а на сервере есть?
Сравните версию PHP, SAPI, расширения, зависимости, конфигурацию и данные. Различия могут быть в php.ini, правах на файлы, переменных окружения или версии кода. Начните с точного сравнения окружений, а не с переписывания кода.
Что делать, если ошибка появляется не каждый раз?
Соберите как можно больше контекста: время, идентификатор запроса, входные данные, параллельные запросы и состояние внешних сервисов. Проверьте, не связана ли ошибка с объёмом данных, таймаутом или гонкой. Для плавающих сбоев особенно полезны структурированные логи с correlation id.
Достаточно ли включить display_errors?
Нет. display_errors показывает сообщение в ответе, но не заменяет журнал. Для сервера важнее log_errors и доступный error_log, а также журналы веб-сервера и приложения. На публичном сайте вывод ошибок в браузер лучше отключить.