debug_backtrace()

Когда ошибка возникает глубоко внутри вложенных вызовов функций, одного сообщения об ошибке редко хватает, чтобы понять как туда попал код. Функция debug_backtrace() отвечает на этот вопрос: она возвращает снимок стека вызовов в точной точке, где вы её вызываете, позволяя увидеть, какая функция вызвала какую, в каком файле и на какой строке. На этой странице описаны сигнатура функции, структура возвращаемого array, практические паттерны использования и место debug_backtrace() среди инструментов отчётности об ошибках PHP.

Что возвращает debug_backtrace()

debug_backtrace() возвращает array ассоциативных array — по одному элементу на каждый кадр стека, упорядоченных от самого внутреннего вызова (там, где вы её вызвали) до точки входа скрипта. Функция никогда не генерирует исключение и не останавливает выполнение — она просто сообщает о текущем стеке.

Сигнатура:

debug_backtrace(int $options = DEBUG_BACKTRACE_PROVIDE_OBJECT, int $limit = 0): array

Параметры

• $options (int) — битовая маска, определяющая содержимое каждого кадра:
  • DEBUG_BACKTRACE_PROVIDE_OBJECT (по умолчанию) — включает фактический object для вызовов методов.
  • DEBUG_BACKTRACE_IGNORE_ARGS — исключает индекс args, что уменьшает объём вывода и позволяет избежать удержания ссылок на большие аргументы.
• $limit (int) — максимальное количество кадров для возврата. 0 (по умолчанию) означает весь стек. Полезно, когда нужен только непосредственный вызывающий.

Каждый кадр

Каждый кадр — это ассоциативный array, который может содержать:

• function — имя вызванной функции или метода.
• line — строка, из которой был сделан вызов.
• file — файл, из которого был сделан вызов.
• class — имя класса, для вызовов методов.
• object — экземпляр object, когда установлен флаг DEBUG_BACKTRACE_PROVIDE_OBJECT.
• type — -> для вызовов экземпляра, :: для статических вызовов, отсутствует для обычных функций.
• args — аргументы, переданные в вызов (если не используется DEBUG_BACKTRACE_IGNORE_ARGS).

Базовый пример: трассировка стека вызовов

Этот скрипт проходит через три вложенные функции и выводит читаемую трассировку из самой глубокой:

<?php
function levelThree() {
    $trace = debug_backtrace();
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() at line {$frame['line']}\n";
    }
}
function levelTwo() { levelThree(); }
function levelOne() { levelTwo(); }
levelOne();

Вывод:

#0 levelThree() at line 8
#1 levelTwo() at line 9
#2 levelOne() at line 10

Кадр #0 — это место, где была вызвана debug_backtrace(), а каждый последующий кадр — вызывающий выше. Используйте print_r($trace) вместо цикла, если хотите сразу увидеть все ключи (file, args и так далее).

Поиск вызывающего

Распространённый, точечный сценарий использования — выяснить, кто вызвал текущую функцию, для целей логирования или предупреждений об устаревании. Передайте DEBUG_BACKTRACE_IGNORE_ARGS, чтобы результат был компактным, и 2 как лимит, затем прочитайте кадр с индексом 1 (индекс 0 — текущая функция):

<?php
function logCaller() {
    $caller = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1] ?? null;
    if ($caller) {
        echo "Called by {$caller['function']}() on line {$caller['line']}\n";
    }
}
function doWork() {
    logCaller();
}
doWork();

Вывод:

Called by doWork() on line 11

Защита ?? null важна, когда logCaller() вызывается на верхнем уровне, где кадра 1 не существует.

Когда использовать

• Логирование и диагностика — прикрепите трассировку к записи лога, чтобы восстановить, как было достигнуто неожиданное состояние.
• Уведомления об устаревании — сообщайте о конкретном вызывающем функцию, которую вы выводите из употребления.
• Пользовательские обработчики ошибок — обогащайте обратный вызов set_error_handler() окружающим стеком вызовов.
• Понимание потока фреймворка — смотрите, какой middleware или хук привёл в ваш код.

Подводные камни

• Производительность и память. При настройках по умолчанию каждый кадр сохраняет ссылки на args и object, что может быть ресурсоёмким. В горячих путях или при работе с большими аргументами передавайте DEBUG_BACKTRACE_IGNORE_ARGS.
• Продакшн-код. Воспринимайте debug_backtrace() как инструмент отладки. Не оставляйте её вывод в консоль на продакшне — направляйте вывод в лог.
• Нужен просто вывод? Используйте debug_print_backtrace(), которая выводит отформатированную трассировку напрямую, не возвращая array.
• Внутри исключения? Объект Exception уже содержит трассировку через $e->getTrace() и $e->getTraceAsString().

Типы ошибок PHP в кратком изложении

debug_backtrace() наиболее полезна, когда вы уже знаете, что ошибка произошла, и вам нужен контекст. Ошибки PHP делятся на несколько широких категорий:

• Ошибки разбора (синтаксические) — некорректный код, который парсер отклоняет до выполнения, например, отсутствующая точка с запятой или незакрытая скобка. Они фатальны.
• Логические ошибки — код выполняется, но выдаёт неверный результат; сообщения об ошибке нет, что как раз и является ситуацией, когда помогает трассировка.
• Ошибки времени выполнения — возникают во время работы скрипта, начиная от нефатальных notices и warnings (неопределённая переменная, отсутствующий include, предупреждения о делении) до фатальных ошибок (вызов метода на не-object, превышение лимита памяти), которые останавливают выполнение.

Чтобы управлять тем, какие из них отображаются, задайте уровень с помощью error_reporting(). В процессе разработки включайте всё:

<?php
// Report all errors, notices and warnings, and show them
error_reporting(E_ALL);
ini_set('display_errors', '1');

graph TD;
    A[PHP Error] -->|invalid code| B(Parse / Syntax)
    A -->|wrong result| C(Logical)
    A -->|while running| D(Runtime)
    D --> E(Notice / Warning)
    D --> F(Fatal Error)

Связанные темы

• debug_print_backtrace() — вывод форматированной трассировки.
• error_reporting() — выбор сообщаемых ошибок.
• trigger_error() — генерация собственных ошибок.
• PHP Exceptions — структурированная обработка ошибок с try/catch.

Практика