500+: Corban manual

Corban, dear! — отладочная библиотека для PHP. Простая в установке и использовании библиотека существенно упростит процесс отладки PHP приложений.

Использование

Библиотека предоставляет несколько функций упрощающих отладку приложения:

cd(), cdx() — вывод информации о переменной;
cm(), cmx() — вывод отладочного сообщения;
ci(), cs() — инициализация и вывод таймера.

Простой пример использования:

 include_once('corban.lib.php');
 cd ($_SERVER);

Подключение файла corban.lib.php

В PHP файл можно подключить несколькими способами: непосредственно в скрипте с помощью конструкций require или include, или же с помощью директивы auto_prepend_file, которую можно установить непосредственно в файле php.ini или же через файл .htaccess (рекомендуемый вариант). Предварительно можно определить конфигурационные константы библиотеки.

Пример подключения непосредственно в скрипте с помощью конструкций require или include:

 define('CORBAN_OUTPUT', 4);
 include_once('corban.lib.php');

Пример подключения с помощью директивы auto_prepend_file через файл .htaccess:

SetEnv	CORBAN_OUTPUT	4
php_value	auto_prepend_file	/path/to/corban.lib.php

Примечание: При необходимости, отключить подключение файла можно с помощью специального значения none.

php_value	auto_prepend_file	none

Описание функций

cd($val, $msg=null, $die=false) — Функция выводит значение переменной (в том числе объектов и ресурсов) с комментариями. Параметры:

$val — Переменная, значение которой необходимо вывести.
$msg — Отображаемое при выводе название переменной и комментарий в формате «varname#comment», где «#» — разделитель (необязательный параметр, по умолчанию null).
$die — Определяет прервать ли работу скрипта после вывода (необязательный параметр, по умолчанию false).

Пример:

 $a = array (1, 2, 3);
 cd($a, 'a#Array a');

Вывод:

Array a
	$a	[0] = 1
	$a	[1] = 2
	$a	[2] = 3

cdx($val, $msg=null) — Аналогична по работе вызову функции cd(), с установленным в true параметром $die.

cm($msg, $param=null, $die=false) — Функция выводит отладочное сообщение, и значение переменной, без информации о ней. Параметры:

$msg — Отладочное сообщение.
$param — Переменная (необязательный параметр, по умолчанию null).
$die — Определяет прервать ли работу скрипта после вывода (необязательный параметр, по умолчанию false).

cmx($msg, $param=null) — Аналогична по работе вызову функции cm(), с установленным в true параметром $die.

ci($name=0) — Функция инициализирует таймер, с заданным именем. Используется вместе с cs(). Параметры:

$name — Имя таймера (необязательный параметр).

cs($name=0, $comment=null) — Функция выводит значение таймера с заданным именем $name, или же таймер по умолчанию, если параметр не указан. Используется вместе с ci(). Параметры:

$name — Имя таймера (необязательный параметр).
$comment — Строка комментария.

Пример:

 ci ('a');
 sleep(10);
 cs ('a', 'Script execution time:');

Вывод:

Script execution time:
10.060

corban_fix_output() — Функция вставляет отладочный вывод перед закрывающим тегом </body>, тем самым предотвращая девалидацию html в следствии использования библиотеки. Необходимо вызвать до первого вывода данных скриптом.

corban_shutup() — Функция принудительно прекращает вывод отладочной информации. Её вызов необходим в случаях, когда необходимость в выводе отладочной информации отпадает, например при отдаче данных в виде json или же бинарных данных.

Конфигурационные константы библиотеки

CORBAN_OUTPUT, по умолчанию 2 (CORBAN_OUTPUT_BUFFER). Определяет тип отладочного вывода. Может принимать значения:

1 (CORBAN_OUTPUT_INLINE) для вывода непосредственно по мере вызова функции cd() и прочих,
2 (CORBAN_OUTPUT_BUFFER) для буферизированного вывода по окончании выполнения скрипта,
3 (CORBAN_OUTPUT_CONSOLE) для вывода во всплывающее окно,
4 (CORBAN_OUTPUT_FILE) для вывода в файл (дополнительно необходимо задать константу CORBAN_FILE_PATH и настроить права записи).

CORBAN_FORMAT, по умолчанию 1 (CORBAN_FORMAT_HTML). Определяет формат отладочного вывода. Может принимать значения:

1 (CORBAN_FORMAT_HTML) для вывода в формате html,
2 (CORBAN_FORMAT_TEXT) для вывода в виде текста.

CORBAN_FIX_OUTPUT, по умолчанию не определена. Предотвращает девалидацию html в следствии использования библиотеки. Может принимать любые значения.

CORBAN_FILE_PATH, по умолчанию не определена. Определяет путь к файлу corban.log, в который будет производиться отладочный вывод. Если константа не определена, то библиотека будет пытаться записывать данные в файл corban.log лежащий в папке с текущим выполняемым скриптом. Необходимо так же установить права записи на файл corban.log.

CORBAN_SHOW_CLASS_METHOD, по умолчанию не определена. Определяет выводить или нет методы объектов.

CORBAN_BLABLA, по умолчанию не определена. Определяет отображать или нет префикс (CORBAN_PREFIX) перед отладочным выводом.

Примечание: Установить значения констант через файл .htaccess можно с помощью директивы Apache SetEnv. Пример:

SetEnv	CORBAN_OUTPUT	4

Валидный html

По умолчанию, при буферизированном выводе (CORBAN_OUTPUT_BUFFER) или же выводе во всплывающее окно (CORBAN_OUTPUT_CONSOLE), для предотвращения внесения искажений в дизайн, все отладочные сообщения выводятся после закрывающего тега </body>. Это приводит к тому, что html код перестает быть валидным. Для того чтобы избежать этого необходимо либо перед подключением библиотеки определить константу CORBAN_FIX_OUTPUT, либо после подключения, но обязательно перед выводом , вызвать функцию corban_fix_output(). После этого все отладочные сообщения будут выведены перед закрывающим тегом </body>.

История создания

Работа над библиотекой «Corban, dear!» была начата в компании Softerra в 1999 году, на заре ее становления. В 2002 году она была выложена под лицензией GNU GPL в составе PHP Developer Library. В дальнейшем библиотека поддерживалась и развивалась вне пределов компании.

«Corban» — неправильное написание имени Корбена Далласа (Korben Dallas) из фильма «Пятый элемент» (The Fifth Element).