Отладка и журналирование¶

При разработке тем и плагинов часто возникает необходимость выводить отладочную информацию. Grav 2.0 сохраняет все инструменты отладки фронтенда, знакомые вам по 1.7, и добавляет отдельный рабочий процесс для нового интерфейса Admin2, который представляет собой одностраничное приложение на JavaScript, общающееся с плагином API, а не набор страниц Twig, рендерящихся на сервере.

Эта страница разделена на две части:

1. Отладка фронтенда (темы, плагины, рендеринг страниц) — работает так же, как всегда.
2. Отладка админки (Admin2 + API) — у неё свои инструменты, потому что старая HTML-панель отладки не может рендериться внутри SPA.

Отладка фронтенда¶

Панель отладки¶

Grav поставляется с панелью отладки для фронтенда. По умолчанию она выключена, и её можно включить глобально или только для вашего окружения разработки через файл конфигурации system.yaml:

1
2
3
4
5

debugger:
  enabled: true                     # включает отладчик Grav и настройки ниже
  provider: clockwork               # 'clockwork' (рекомендуется) или 'debugbar'
  shutdown:
    close_connection: true          # закрыть соединение перед onShutdown(). При отладке задайте false.

При provider: debugbar панель отладки PHP рендерится прямо на странице и показывает время обработки, использование памяти и вкладки Messages, Request, Exceptions, Configuration и Timeline.

При provider: clockwork те же данные передаются через заголовки ответа, а не рисуются на странице, и вы читаете их в расширении Clockwork для браузера (доступно для Chrome и Firefox). Clockwork — рекомендуемый провайдер для 2.0, потому что тот же механизм питает и отладку админки (см. ниже).

Команда dump для PHP¶

Чтобы просмотреть переменную или объект PHP во время рендеринга фронтенда, используйте команду dump(). Она принимает любое допустимое значение PHP и выводит форматированное цветное представление:

dump($myvariable);

Также можно отправить значение на вкладку Messages отладчика, не записывая его в поток вывода:

$this->grav['debugger']->addMessage($myvariable);

Команда dump для Twig¶

Переменные Twig можно выводить из шаблона. Для этого нужен отладчик Twig, включённый глобально или для окружения в system.yaml:

1
2

twig:
  debug: true                       # включает отладчик Twig

1

{{ dump(page.header) }}

Несколько дампов можно подписать, чтобы их было легко различить:

1

{{ dump('page.header output:', page.header) }}

Вывод в консоль браузера из Twig¶

Когда страница не перезагружается или нужно посмотреть значение до того, как страница будет возвращена, выведите его прямо в консоль браузера:

<script> console.log({{ page.header|json_encode|raw }}) </script>

Отладка Admin2¶

Новая админка — это одностраничное приложение. Она никогда не рендерит серверную HTML-панель отладки, поэтому классическая панель на странице там не появляется. Вместо неё Admin2 даёт два дополняющих друг друга инструмента, оба работают на тех же данных Clockwork, которые Grav уже создаёт.

Сначала включите отладчик в system.yaml (провайдер clockwork, как показано выше). Тогда каждый ответ API будет нести заголовки Clockwork — этого достаточно для обоих инструментов ниже.

Встроенная панель API Debug¶

Когда отладчик включён, в левом нижнем углу Admin2 появляется маленькая иконка жука. Нажатие на неё открывает панель API Debug, для которой не нужно расширение браузера:

• Она перечисляет последние запросы к API, сделанные админкой, показывая для каждого метод, статус, путь и длительность на стороне клиента.
• Нажатие на запрос загружает его серверный профиль Clockwork: время ответа, измеренное на сервере, число запросов к базе данных, использование памяти и полный вывод логов / дампов для этого запроса.

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

Расширение Clockwork для браузера¶

Для более подробного просмотра установите расширение Clockwork для браузера. Поскольку Admin2 общается с API через XHR/fetch и каждый ответ API несёт заголовок X-Clockwork-Id, расширение автоматически подхватывает каждый отдельный вызов API. Вы получаете полные панели таймлайна, логов, базы данных и производительности Clockwork для каждого запроса — точно так же, как при обычной загрузке страницы.

Чтение данных профилировщика с удалённого сайта¶

Clockwork читает свои данные из эндпоинта /__clockwork/ на вашем сайте. Этот эндпоинт отвечает очень рано в процессе загрузки Grav — до того, как появляются сессии, учётные записи и плагины, поэтому авторизовать его не по кому: вошедшего пользователя ещё нет. Начиная с Grav 2.0.22 он поэтому отвечает только на два вида запросов:

• запросы с самой машины, на которой работает Grav, и
• запросы с общим секретом, который вы задали в system.debugger.token.

На локальном сайте для разработки ничего не меняется: вы открываете localhost, и Grav видит loopback-запрос, поэтому Clockwork продолжает работать без настройки.

На удалённом сайте, тестовом сервере или виртуальной машине, доступной по сети, ваш браузер — не та машина, на которой работает Grav. Clockwork покажет:

Authentication failed. Debugger metadata requires authentication.

с полем для пароля. Это собственное приглашение Clockwork, и он запрашивает токен. Задайте его в system.yaml:

1
2
3
4

debugger:
  enabled: true
  provider: clockwork
  token: 'a-long-random-secret'     # общий секрет для удалённого чтения данных /__clockwork/

Затем введите то же значение в поле пароля Clockwork. Расширение выполняет рукопожатие с /__clockwork/auth и запоминает результат, поэтому вас спросят только один раз за браузер.

Если вы предпочитаете вообще не задавать токен, данные всё равно можно прочитать с самого сервера, например по SSH:

curl -s http://localhost/__clockwork/latest

Отладка API и хуков¶

Код плагина, выполняющийся на пути API, — например, обработчик события onApi* или контроллер, расширяющий AbstractApiController, — не должен вызывать dump(). API возвращает JSON, а dump() пишет в это тело, портя ответ.

Вместо этого отправьте значение отладчику. Clockwork его перехватит и покажет и в панели API Debug, и в расширении браузера, не трогая тело ответа:

// Где угодно, где доступен контейнер Grav (например, в хуке onApi*):
$this->grav['debugger']->addMessage($myvariable, 'info');

У контроллеров, расширяющих AbstractApiController, есть удобный помощник, который делает то же самое и сам кодирует массивы и объекты в JSON:

// Внутри метода контроллера API:
$this->debug($myvariable, 'my-label');
$this->debug(['route' => $route, 'count' => $items], 'lookup');

Оба вызова ничего не делают, когда отладчик выключен, поэтому их безопасно оставлять в ветках кода для разработки. Откройте панель API Debug, нажмите нужный запрос — и ваше сообщение появится в списке Log / dumps.

Отображение ошибок¶

Подробная страница ошибки показывает трассировки и соответствующие блоки кода, помогая локализовать критические ошибки. По умолчанию она выключена, поэтому включите её для разработки:

1
2

errors:
  display: true

На продакшене отключите подробную страницу и полагайтесь на файл журнала:

1
2
3

errors:
  display: false
  log: true

Журналирование¶

Grav предоставляет простое, но мощное средство журналирования. Используйте любой из стандартных уровней важности:

1
2
3
4
5
6
7
8

$this->grav['log']->info('My informational message');
$this->grav['log']->notice('My notice message');
$this->grav['log']->debug('My debug message');
$this->grav['log']->warning('My warning message');
$this->grav['log']->error('My error message');
$this->grav['log']->critical('My critical message');
$this->grav['log']->alert('My alert message');
$this->grav['log']->emergency('Emergency, emergency, there is an emergency here!');

Все сообщения дописываются в файл /logs/grav.log. Журналирование работает одинаково на фронтенде и на пути API, что делает его надёжным запасным вариантом, когда нужна запись о том, что происходило между запросами.