Журналы и отладка

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

Где лежат журналы

Файл или папка	Что в нём
`var/log/system.log`	Сообщения уровня `info` и выше
`var/log/debug.log`	Отладочные сообщения; пишутся в режиме разработчика
`var/log/exception.log`	Исключения с полным стеком вызовов
`var/report`	Отчёты об ошибках, показанных посетителю в рабочем режиме

Следить за журналом удобно командой, которая показывает новые строки по мере появления:

tail -f var/log/system.log

Запись в журнал

Свой код пишет в журнал через Psr\Log\LoggerInterface из конструктора:

// app/code/Acme/Hello/Model/ReviewService.php
namespace Acme\Hello\Model;
 
use Psr\Log\LoggerInterface;
 
class ReviewService
{
    public function __construct(private LoggerInterface $logger) {}
 
    public function approve(int $reviewId): void
    {
        $this->logger->info('Отзыв одобрен', ['review_id' => $reviewId]);
    }
}

В файле var/log/system.log появится строка с датой, уровнем INFO, текстом и данными из массива. Второй аргумент — любые сведения, которые помогут разобраться позже.

Уровни сообщений

Метод	Когда использовать
`debug()`	Подробности для разработчика
`info()`	Обычное событие: импорт завершён
`warning()`	Что-то подозрительное, но работа продолжается
`error()`	Действие не выполнено
`critical()`	Серьёзный сбой, требующий внимания

Журнал исключений

Пойманное исключение передают в журнал целиком:

// app/code/Acme/Hello/Model/ReviewService.php
try {
    $this->reviewRepository->save($review);
} catch (\Exception $e) {
    $this->logger->critical($e);
}

Сообщение и стек вызовов попадут в var/log/exception.log. Не оставляйте блок catch пустым: ошибка исчезнет бесследно.

Как направить сообщения модуля в отдельный файл var/log/hello.log, показано в уроке о виртуальных типах.

Ошибка на странице

В режиме разработчика текст ошибки и стек вызовов показываются прямо на странице. В рабочем режиме посетитель видит только номер отчёта, а сам отчёт лежит в папке var/report в файле с этим номером в имени.

Подсказки шаблонов

Чтобы узнать, какой шаблон и блок выводят часть страницы, включите подсказки:

bin/magento dev:template-hints:enable
bin/magento cache:clean

Каждая часть страницы будет обведена рамкой с путём к файлу .phtml и именем класса блока. После работы выключите их командой dev:template-hints:disable.

Журнал запросов к базе

bin/magento dev:query-log:enable

Все запросы SQL начнут записываться в var/debug/db.log. Так находят лишние и медленные запросы. Журнал быстро растёт, поэтому его отключают командой dev:query-log:disable.

Пошаговая отладка

Расширение PHP Xdebug позволяет остановить выполнение на нужной строке и посмотреть значения переменных в редакторе. В Magento, где вызов проходит через плагины и сгенерированные классы, это часто единственный способ понять, что происходит.

Где искать причину

Что видно	Куда смотреть
Пустая страница или ошибка 500	`var/log/exception.log`, `var/report`, журнал ошибок PHP
Страница без стилей	Консоль браузера, папка `pub/static`
Правка не видна	Кеш: `bin/magento cache:clean`
Ошибка о несовпадении аргументов конструктора	Папка `generated`: удалить содержимое
Бесконечная загрузка таблицы в панели	Консоль браузера и `var/log/system.log`

Частая ошибка

Для отладки используют var_dump() или echo прямо в классе. На странице с кешем вывод не появляется или запоминается и показывается всем посетителям, а в ответах API ломает JSON. Пишите в журнал через LoggerInterface и читайте файл в var/log.

Спасибо, что читаете!