Использование “Расширенной отладки» v.10 для InstantCMS 2.3
Всё управление отладкой вынесено в админку в раздел «Настройки – Отладка». Все настройки разделены по вкладкам.
Настройки в Админке
Вкладка «Отладка»
Включить режим отладки
Разрешает/запрещает отладку на сайте. При выключенном флажке «Отладка» в память не загружается. Выполняется лишь загрузка одного маленького конфига из файла и проверка одной глобальной константы во всех местах вызова отладки. Никакие функции отладки при этом не доступны.
Минимальная выводимая информация при включённой отладке – суммарная таблица со значениями времени выполнения скрипта и другими параметрами (смотри ниже в этом документе).
При включении режима отладки выводится постоянное предупреждение об этом в «Панели управления» на каждой странице.
Показывать отладочную информацию только администраторам
При выключенном флажке отладочная информация показывается только администраторам сайта (не путайте с группой Администраторы), другим посетителям страницы выдаются как обычно. Это позволяет исследовать работу сайта не прекращая к нему доступ пользователей.
Обратите внимание, что при этом скрипты «Отладки» всё равно загружаются при каждом создании страницы, и для обычных пользователей тоже. А это притормаживает работу всего сайта. Пусть увеличение времени составляет всего несколько процентов в зависимости от выбранных режимов отладки, но всё равно, если отладка не нужна, её лучше выключать совсем.
Показывать полное (блочное) выделение памяти скрипту
При выключенном флажке показывается точное использование памяти скриптом в мегабайтах. Этот режим может быть полезен при отладке кода.
При включенном флажке показывается реальное выделение памяти, так как PHP выделяет память для скриптов блоками (их размер задаётся в настройках PHP). Такой режим удобнее для администраторов серверов.
Имитировать сетевые задержки (в миллисекундах)
Делает паузу перед отдачей готовой страницы с сервера. В отличие от стандартного встроенной функции позволяет задать длительность этой паузы в миллисекундах. Для отключения поставьте 0.
Стандартная встроенная в Инстант функция задержки в этой версии отладки отключена за ненадобностью.
Вкладка «Ошибки PHP»
Разрешает перехват ошибок PHP и вывод их в лог. Для каждой ошибки указывается её тип, описание и место возникновения. В отличие от обычного стандартного вывода ошибок, информация о них не портит страницу, а выводится в лог внизу страницы над суммарной таблицей параметров времени выполнения. А также по возможности делается трассировка и опционально выводится контекст (состояние переменных, аргументов и т.д.)
Есть возможность уведомления админа о возникновении критических (фатальных) ошибок тремя способами и вывода пользователям заданного текста вместо описания ошибок.
Доступен выпадающий список глубины трассировки.
Включить строгий режим перехвата ошибок для точной отладки
Устанавливает более глубокий уровень перехвата ошибок и предупреждений отладки (E_ALL | E_STRICT). Полезно при отладке своего кода для выявления скрытых ошибок. Если выключено, то используется глубина регистрации ошибок из настроек сервера.
Разрешить стандартный вывод ошибок на экран (иногда полезно при отладке)
Разрешает дополнительный стандартный вывод ошибок на экран. Может быть полезно при ошибках в ядре (например, при экспериментах с хаками или после неудачного обновления системы). Ошибки показываются всем пользователям, в том числе и гостям, независимо от галки «Показывать отладочную информацию только администраторам».
Выводить в лог на экран контекстные данные ошибок (переменные, объекты), если это возможно
Если PHP возвращает эту информацию, то в отдельном блоке выводится контекст ошибки: для функций и методов классов – локальные переменные, аргументы вызова, для глобальной области видимости – ВСЕ переменные скрипта, существующие на момент ошибки, в том числе и суперглобальные. В последнем случае на экран может быть выведено слишком много информации, которую пользователям видеть нельзя. Поэтому не забывайте разрешать вывод отладочной информации только администраторам.
При критической ошибке уведомлять админа (укажите id админа)
Для отправки сообщений админу о возникающих критических ошибках укажите id админа. А затем разрешите отправку одним или несколькими способами.
Для отправке по электронной почте укажите e-mail админа.
При отправке личным сообщением на сайте оно отправляется от имени пользователя с указанным id самому же себе.
Уведомление на сайте отправляется стандартным образом, как и любые системные уведомления.
При любом типе уведомления в сообщении указываются: время, тип, описание ошибки, место её возникновения (файл, строка), адрес страницы и пользователь, под которым эта страница была открыта.
Обратите внимание, что админ получит сообщение о каждой произошедшей критической ошибке у всех пользователей на любых страницах. При большом количестве таких ошибок почта, переписка или лента уведомлений могут быть завалены сообщениями и их придётся чистить вручную. Не стоит надолго оставлять уведомления включёнными в случае, если на сайте часто возникают критические ошибки. Эта возможность больше подходит для оперативной реакции на возможные ошибки после обновления или добавления компонентов.
При критической ошибке показывать пользователям следующее сообщение вместо ошибочной страницы
В случае критической ошибки выводит пользователям указанное сообщение. Html-теги обрезаются, выводится только чистый текст.
Текст показывается пользователям (не админам) при выполнении следующих условий:
- разрешена отладка;
- вывод инфы об отладки разрешён только админам;
- разрешён перехват ошибок PHP;
- присутствует текст для вывода (поле не пустое);
Админам в любом случае показывается описание ошибки.
Учтите, что если включена галка «Разрешить стандартный вывод ошибок на экран», то дополнительно к тексту пользователю будет выведено и описание этой критической ошибки, что чаще всего нежелательно.
Вкладка «Контрольные точки»
Разрешает вывод всех контрольных точек в лог внизу страницы под суммарной таблицей. С помощью КТ можно также включать временный вывод запросов к БД и/или инклудов на отдельных участках кода. Описание и примеры вызовов КТ даны внизу этого документа.
Для каждой КТ показывается время выполнения с начала скрипта или с момента предыдущей КТ, если такая уже была.
Глубина трассировки для контрольных точек
Выпадающий список. Задаёт общую для всех КТ глубину трассировки вызовов (то есть, показывает последовательность вызовов по функциям, классам и файлам скриптов до КТ). При необходимости, глубину трассировки можно задавать для каждой отдельной КТ при её вызове в коде.
Вкладка «База данных»
Разрешает вывод в лог попыток подключений и запросов к базам данных с подробной информацией о них. Доступен выпадающий список глубины трассировки.
Для запросов на изменение показывается результат – количество обработанных строк, для запросов на выборку – количество возвращённых строк. Запросы с ошибками и предупреждениями подсвечиваются цветом.
Для каждого коннекта или запроса показывается время его выполнения.
Выводить в лог результаты SQL-запросов
Разрешает выводить в лог результаты SQL-запросов. Вывод делается только для тех запросов, которые вернули хотя бы одну строку.
Строка для фильтра SQL-запросов по части строки запроса
Включает показ только тех запросов, в тексте которых присутствует указанная строка. Строка для сравнения используется целиком, ищется по всему тексту запроса, знаки подстановки (типа ? и *) не используются. Фильтр позволяет, например, отобрать запросы только к указанной таблице или содержащие только обращение к указанному полю.
Строка для фильтра SQL-запросов по пути/имени вызывающего файла или класса/функции
Включает показ только запросов, сделанных из функций/классов, в пути или имени файлов которых, или в самом имени этих функций/классов присутствует указанная строка. Например, можно отследить только запросы из одного компонента или из определённой функции.
Подсвечивать "тяжёлые" SQL-запросы с длительностью более указанной, в миллисекундах (0 - отключить подсветку)
Запросы длительностью более указанной (в целых миллисекундах), будут выделяться цветом. При вводе «0» подсветка отключается.
Вкладка «Автозагрузки»
Разрешает вывод в лог информации об автозагрузках классов. Доступен выпадающий список глубины трассировки.
Для каждой автозагрузки показывается время её выполнения и результат (ОК или ошибка).
Строка для фильтра автозагрузок по пути/имени подключаемого файла
Включает показ только тех автозагрузок, в пути или имени файла которых присутствует указанная строка. Например, можно увидеть когда и где производится подключение нужного файла.
Строка для фильтра автозагрузок по пути/имени подключающего файла или класса/функции
Включает показ только автозагрузок, сделанных из функций/классов, в пути или имени файлов которых, или в самом имени этих функций/классов присутствует указанная строка. Например, можно отследить только автозагрузки, вызванные из определённого компонента или из определённой функции.
Вкладка «Инклуды»
Разрешает вывод в лог информации об инклудах файлов.
Для каждого инклуда показывается время его выполнения и результат (ОК или ошибка).
Также доступен выпадающий список глубины трассировки.
В таблице количеств инклудов показывать только 2 и более вызовов или ошибки
При разрешении показывать инклуды, под общей суммарной таблицей показывается ещё одна таблица - список всех подключаемых файлов с указанием сколько раз была попытка их подключения и с количеством ошибок при этом.
Данный флажок позволяет оставить в таблице лишь те файлы, где были ошибки подключения или которые подключались два и более раза. Это удобно для выявления неоптимальной работы с подключаемыми файлами.
Строка для фильтра инклудов по пути/имени подключаемого файла
Включает показ только тех инклудов, в пути или имени файла которых присутствует указанная строка. Например, можно увидеть когда и где производится подключение нужного файла.
Строка для фильтра инклудов по пути/имени подключающего файла или класса/функции
Включает показ только инклудов, сделанных из функций/классов, в пути или имени файлов которых, или в самом имени этих функций/классов присутствует указанная строка. Например, можно отследить только инклуды из определённого компонента или из определённой функции.
Вкладка «События и хуки»
Разрешает вывод в лог информации о событиях и хуках.
Для каждого события и хука показывается место вызова и трассировка. Для хуков дополнительно подсчитывается время их выполнения и опционально выводятся входные данные и возвращаемые результаты.
Также возможно задание глубины трассировки.
Выводить в лог данные и результаты хуков
Разрешает выводить в лог входные данные и возвращаемые результаты хуков.
Таблица хуков
Показывать дополнительную таблицу. Есть несколько вариантов таблицы:
'Только активные хуки - по хукам – показывать только сработавшие хуки и обрабатывающие их контроллеры, группируя их по хукам;
'Только активные хуки - по контроллерам' – показывать только сработавшие хуки и обрабатывающие их контроллеры, группируя их по контроллерам;
'Все зарегистрированные хуки - по хукам – показывать все зарегистрированные хуки и для каждого хука список обрабатывающих контроллеров;
'Все зарегистрированные хуки - по контроллерам' – показывать все контроллеры системы со списком хуков, обрабатываемых каждым контроллером;
'Список произошедших событий' – список событий, произошедших на странице, и сколько раз они случились;
'Список зарегистрированных хуков' – простой список хуков, зарегистрированных во всех контроллерах;
'Список контроллеров' – простой список контроллеров из папки \system\controllers.
Обратите внимание: фильтры по событию и контроллеру применяются к первым четырём таблицам. При задании фильтров эти таблицы могут выводиться сокращённо.
Фильтровать события/хуки по событию
Выпадающий список событий. При выборе любого события в лог будет выводиться информация только о хуках этого события.
Фильтровать хуки по контроллеру
Выпадающий список контроллеров. При выборе любого контроллера в лог будет выводиться информация только о хуках, обрабатываемых в этом контроллере.
Строка для фильтра событий/хуков по пути/имени вызывающего файла или класса/функции
Включает показ только событий/хуков, вызванных из функций/классов, в пути или имени файлов которых, или в самом имени этих функций/классов присутствует указанная строка. Например, можно отследить только события определённого компонента или вызванные из определённой функции.
Подсвечивать "тяжёлые" хуки с длительностью более указанной, в миллисекундах (0 - отключить подсветку)
Хуки длительностью более указанной (в целых миллисекундах), будут выделяться цветом. При вводе «0» подсветка отключается.
Вкладка «Виджеты»
Разрешает вывод в лог информации о виджетах.
Для каждого виджета показывается его имя, время его выполнения, место вызова и трассировка. Опционально можно отображать входные данные и результаты вызовов виджетов.
Выводить в лог данные и результаты виджетов
Разрешает выводить в лог входные данные и возвращаемые результаты виджетов.
В таблице виджетов показывать только активные виджеты
В таблице виджетов будут показаны только виджеты, отображённые на странице. Если флаг снять, то будут показаны все виджеты, зарегистрированные в системе.
Фильтровать по виджету
Выпадающий список всех виджетов для фильтра. При выборе любого виджета в лог будет выводиться информация только о вызовах виджета этого типа. Значение « < Показывать все> » - отключить этот фильтр.
Фильтровать по контроллеру
Выпадающий список контроллеров. При выборе любого контроллера в лог будут выводиться информация только о виджетах этого контроллера. Значение « < Показывать все> » - отключить этот фильтр. Значение « < Пусто> » - показать виджеты, у которых контроллер не указан (виджеты из блока «Общие»).
Подсвечивать "тяжёлые" виджеты с длительностью более указанной, в миллисекундах (0 - отключить подсветку)
Виджеты длительностью более указанной (в целых миллисекундах), будут выделяться цветом. При вводе «0» подсветка отключается.
Вкладка «Кэш»
Разрешает вывод в лог информации об обращениях к кэшу.
Для каждого обращения к кэшу показывается его тип (SET/GET), ключ, время выполнения этого обращения и результат (сколько записано байт или получено значений).
Выводить в лог данные и результаты обращений к кэшу
Разрешает выводить в лог входные данные операций SET и возвращаемые результаты операций GET.
Показывать обращения к кэшу только типа
Позволяет определить, операции какого типа будут выведены в лог: SET, GET или все операции.
Строка для фильтра обращений к кэшу по ключу
Включает показ только тех операций с кэшем, в имени ключа которых присутствует указанная строка. Например, можно отобрать только операции для виджетов или контента.
Строка для фильтра операций с кэшем по пути/имени вызывающего файла или класса/функции
Включает показ только операций с кэшем, вызванных из функций/классов, в пути или имени файлов которых, или в самом имени этих функций/классов присутствует указанная строка.
Также доступен выпадающий список глубины трассировки.
Вкладка «Другое»
Дополнительные возможности.
Показывать в логе вызов контроллера
Разрешает вывод в лог информации о вызове контроллера.
Показывать в логе инициализацию шаблона
Разрешает вывод в лог информации об инициализации шаблона.
Во время инициализации шаблона происходит определение его имени, если оно не задано, выполняется загрузка опций шаблона и некоторые другие начальные действия с шаблоном.
Показывать в логе вызов рендеринга шаблона
Разрешает вывод в лог информации о рендеринге шаблона.
При рендеринге в шаблон подставляются данные (тело страницы, виджеты), подготовленные контроллером и другими частями скрипта. То есть, тут собирается готовый html-код страницы.
Вывод подробной информации в лог
Вывод в лог контрольных точек, запросов к БД, инклудов и обращений к кэшу осуществляется последовательно, в порядке их отработки в коде. Таким образом, можно наглядно видеть что за чем происходит и как меняется.
Для всех КТ, запросов, инклудов, событий/хуков и обращений к кэшу показывается место вызова (файл, класс, функция, строка), а также делается трассировка вызова на заданную глубину.
Несколько слов про подсчёт использованной памяти хуками, виджетами, контроллером и шаблоном. Используется два варианта расчёта. Если за время работы этой части скрипта был достигнут новый пик памяти, значит использование равно разнице между этим пиком и начальным значением памяти на момент старта скрипта. Помечается как 'peak'. Если пик не изменился, тогда использование памяти считается как разница между памятью в конце работы скрипта и в начале. Ставится пометка ‘end’.
Тот же принцип используется и при расчёте значений памяти хуков, виджетов, контроллера и шаблона для основной суммарной таблицы.
Суммарная таблица
Для удобства и наглядности вся информация разбита по столбцам:
Script
script time – время работы скрипта без учёта времени старта PHP-модуля сервера, времени отладки и заданной сетевой задержки
php start time – время старта PHP-модуля на сервере (только для PHP 5.4 и выше)
debug time – время на работу «Отладки» и % от полного времени работы скрипта
full time – полное время работы скрипта, включая старт PHP, отладку и эмуляцию сетевой задержки
emulate lag – время эмуляции сетевой задержки (выводится только при её включении)
check points – количество сработавших точек отладки в коде
PHP
php time – время работы php и процент времени от времени скрипта
autoloads – количество автозагрузок классов, время и % от времени php
includes – количество подключений файлов, время и % от времени php
SQL
sql time – работы sql и процент времени от времени скрипта
connects – количество подключений к БД, время и % от времени sql
queries – количество запросов к БД, время и % от времени sql
Cache (тип кэша files/memory/off – файловый/память/выключен)
cache time – время работы кэша и процент времени от времени скрипта
set – количество установок кэша, время и % от времени работы кэша
get – количество считываний кэша, время и % от времени работы кэша
Memory (режим учёта памяти (exact/block – точный/блочный)
script peak – максимальное использование памяти скриптом
start – память в начале работы
end – память в конце работы (скрипт + отладка)
full peak – максимальное использование памяти скриптом и «Отладкой» вместе
debug – память, использованная «Отладкой»
Parts of script
Отдельным блоком внизу таблицы показывается информация о работе частей скрипта.
events/hooks – количество событий и хуков, время хуков и % от времени php, память
widgets – количество вызовов виджетов, их время и % от времени php, память
controller – время работы контроллера и % от времени php, память
template init – время инициализации шаблона и % от времени php, память
rendering – время окончательной сборки html-кода страницы из подготовленных html-текстов контента, виджетов, меню и т.п. и % от времени php, память
Категории, для которых включён вывод подробной отладочной информации, выделяются в таблице жирным шрифтом.
Для КТ алгоритм выделения чуть другой. Строка «check points» и количество КТ выводится только тогда, когда во время работы скрипта отработала хотя бы одна КТ. Это сделано для того, чтобы обратить внимание на наличие в текстах скриптов сработавших контрольных точек.
Текущие параметры отладки
Для наглядности и удобства на вкладке «Отладка» перед настройками показываются текущие сохранённые параметры отладки. Все параметры имеют то же самое цветовое оформление по типам обрабатываемых операций, которое используется в логах (из того же css-файла). При отключении отладки информация о параметрах не выводится.
Справа от названия обрабатываемых операций в скобках приведены дополнительные параметры для этих операций. Некоторые из них обозначаются кратко по-английски.
Например:
table – режим таблицы операций перед логами, если таковая выводится (‘all’ – выводятся все строки таблицы, 'errors_only' – только строки с ошибками, 'active_only' – только активные хуки/виджеты)
log_hook_data – выводить в лог данные и результаты хуков
log_widget_data – выводить в лог данные виджетов
filter – значение фильтра ('_from' – часть имени/пути вызывающего php-файла/класса/функции, ‘_file’ – часть имени/пути подключаемого файла, ‘_sql’ – часть SQL-запроса и т.д.)
query_heavy, hook_heavy и widget_heavy – включить подсветку «тяжёлых» SQL-запросов, хуков и виджетов, выполняющиеся дольше указанного времени
trace – глубина трассировки
В верхнем правом углу блока "Текущие параметры отладки" на странице настройки "Отладки" в Админке выводится установленная версия "Отладки".
Использования точек отладки (контрольных точек)
Для вставки КТ достаточно в нужном месте кода вставить вызов функции обработки КТ. Есть два варианта.
Простой работает при наличии в index.php функции dcp(). Это сокращённое название от «DebugCheckPoint». В архиве на сайте она уже есть, так что это рекомендуемый вариант:
dcp($name, $params, $trace_level, $sql_debug, $include_debug);
Полный вариант:
if (DEBUG_ON) cmsDebug::getInstance()->checkPoint($name, $params, $trace_level, $sql_debug, $include_debug);
При таком варианте проверка константы DEBUG_ON перед любым обращением к классу отладки обязательна!
Все параметры необязательные:
string $name Название точки, выводится в лог в кавычках после "CheckPoint"
mixed $params Переменная/строка параметров для лога, выводится в наглядном виде с цветовым оформлением в отдельном блоке. Если сюда передать только одну переменную-массив, то содержимое массива будет выведено в удобочитаемой форме, как при выводе через var_dump, только лучше.
int $trace_level Глубина трассировки вызовов: 0 - выключить, '' - по умолчанию из конфига, цифра больше 0 – глубина трассировки
bool $sql_debug Временно включить показ SQL с этой контрольной точки до следующей КТ
bool $include_debug Временно включить показ инклудов с этой контрольной точки до следующей КТ
Примеры:
dcp('functionName');
Выведет в лог название КТ "functionName" и значения параметров времени выполнения скрипта в этой точке. Ограничив участок кода двумя такими точками можно увидеть время выполнения этого блока кода, изменения занятой памяти и т.д.
dcp('functionName',$param);
Дополнительно к предыдущему варианту выведет значение переменной $param
dcp('functionName', array('param1' => $param1, 'param2' => $param2), 5, true, true);
Выведет в лог название КТ "functionName" и значения параметров времени выполнения скрипта в этой точке. Дополнительно покажет значение переменных $param1 и $param2. Включит показ трассировки на 5 уровней. Разрешит вывод лога запросов к базе данных и инклудов до конца скрипта или до следующей КТ (на которой можно опять временно включить их вывод).