# Собственные вызовы Debug

← [К разделу «Публичная отладка»](README.md)

`App\Helpers\Debug::panel()` отправляет произвольное значение во вкладку
**Данные** публичного Debug Toolbar. Метод не вставляет HTML в страницу, не
останавливает выполнение и не записывает данные в БД или файл.

## Основной вызов

```php
use App\Helpers\Debug;

Debug::panel($value, 'Понятная подпись');
```

Подпись необязательна. Если её не передать, helper попытается определить имя
переменной из строки исходного файла:

```php
Debug::panel($catalogSettings);
```

Явная подпись надёжнее для сохранённого PHP-кода, многострочного выражения и
нескольких вызовов рядом.

## Что можно передавать

```php
Debug::panel(array(
    'document_id' => $documentId,
    'rubric_id' => $rubricId,
    'fields' => $fieldValues,
), 'Данные перед сохранением');

Debug::panel($documentObject, 'Загруженный документ');
Debug::panel($sql, 'Сформированный SQL');
Debug::panel($responseCode, 'Код ответа шлюза');
```

- массивы раскрываются как дерево;
- для объекта показывается класс и его публичные свойства;
- рекурсивная ссылка помечается, а не зацикливает панель;
- resource заменяется текстовым описанием;
- максимальная глубина нормализации — 8 уровней.

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

## Метод возвращает исходное значение

Это позволяет временно посмотреть результат внутри выражения:

```php
$document = Debug::panel(
    $repository->find($documentId),
    'Результат DocumentRepository::find'
);
```

Для постоянного кода отдельный вызов читается лучше и его проще удалить.

## В системном блоке или коде рубрики

Сохранённый PHP выполняется через совместимый runtime. Можно использовать
полное имя helper:

```php
\App\Helpers\Debug::panel($fields, 'Поля из кода рубрики');
```

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

## Диагностика запроса

Настройка запроса **Показать SQL** использует этот же защищённый канал. SQL
появляется в **Данные** с подписью вида `SQL запроса #12`, но не выводится в
карточку или HTML посетителя.

Для обычного SQL отдельный `Debug::panel()` чаще не нужен: вкладка **SQL** уже
показывает выполненный запрос, длительность и место вызова. Добавляйте свой
вызов, если нужно увидеть запрос **до** выполнения или сравнить несколько
вариантов построения.

## Что не использовать в публичной странице

```php
Debug::echo($value);
Debug::print($value);
Debug::exp($value);
```

Эти legacy-методы печатают отладочный HTML прямо в ответ. Его может увидеть
посетитель; он также способен сломать JSON, заголовки, редирект или вёрстку.

`Debug::dump()` записывает `debug.html` на диск и не является вкладкой Toolbar.
Для публичной диагностики используйте `Debug::panel()`.

## Секреты и персональные данные

Нельзя передавать пароли, Bearer-токены, ключи платежей, полный cookie или данные
банковской карты. Автомаскирование работает по ключам массива и не распознает
секрет, переданный отдельной строкой:

```php
// Нельзя: scalar будет показан как есть.
Debug::panel($apiToken, 'API token');

// Допустимо для проверки структуры без раскрытия значения.
Debug::panel(array(
    'token' => '***',
    'expires_at' => $expiresAt,
), 'Состояние токена');
```

Записи живут только до конца текущего PHP-запроса. Они не заменяют аудит,
application log или журнал задач интеграции.