PHP-CTPP API
Оглавление
Введение
PHP расширение библиотеки CTPP предназначено для языков PHP4 и PHP5. Для PHP4 используется только процедурное API, а для PHP5 можно использовать как процедурное API, так и объектное.
Всего насчитывается 12 функций, разделенных на три группы: функции загрузки и обработки шаблонов, функции вставки параметров и вывода результатов работы и функции отладки.
Описание функций и примеры работы даны ниже.
Переменные конфигурации шаблонизатора
Библиотека позволяет установить некоторые значения внутренних переменных. Для большинства случаев нет необходимости менять значения, заданные по умолчанию. Увеличение или уменьшение большинства из этих параметров никак не влияют на производительность системы в целом. Если вы не уверены в предназначении какого-либо параметра, не меняйте его.
ctpp.arg_stack_size
Размер внутреннего стека аргументов.
ctpp.code_stack_size
Размер внутреннего стека точек возврата.
ctpp.steps_limit
Максимальное время исполнения программы в количестве выполненных инструкций. Используется для ограничения размера выполняемых шаблонов.
ctpp.cache_bytecode
Флаг кеширования байткода. Если включен, загруженный байткод кешируется системой, минимизируя обращения к диску.
ctpp.max_functions
Максимальное количество поддерживаемых встроенных функций.
Инициализация шаблонизатора
Создание объекта:
$Template = new ctpp();
$Template = ctpp_new();
set_steps_limit, ctpp_set_steps_limit
Задание лимита исполнения шаблона. В ряде случаев бывает полезно ограничить максимальное время исполнения шаблона. Для этого служит функция ctpp_set_steps_limit(set_steps_limit).
$Template -> set_steps_limit(10240);
ctpp_set_steps_limit($Template, 10240));
Значение по умолчанию - 1048576 (1024 * 1024), этого должно хватить для большинства случаев использования библиотеки.
Функции загрузки
include_dirs, ctpp_include_dirs
Задание списка каталогов поиска файлов. Функция аналогична стандартной set_include_path, но на вход принимает не строку, а массив строк:
$Template -> include_dirs(Array('/каталог1', '/каталог2'));
ctpp_include_dirs($Template, Array('/каталог1', '/каталог2'));
parse_template, ctpp_parse_template
Загрузка и парзинг шаблона.
$Bytecode = $Template -> parse_template("example.tmpl");
$Bytecode = ctpp_parse_template($Template, "example.tmpl");
Функции возвращают ресурс, содержащий в себе байткод, готовый к исполнению.
load_bytecode, ctpp_load_bytecode
Загрузка заранее откомпилированного байткода.
$Bytecode = $Template-> load_bytecode("example.ct2");
$Bytecode = ctpp_load_bytecode($Template, "example.ct2");
Функции возвращают ресурс, содержащий в себе байткод, готовый к исполнению.
free_bytecode, ctpp_free_bytecode
Выгрузка байткода и освобождение ресурсов.
$Template-> free_bytecode($Bytecode);
ctpp_free_bytecode($Template, $Bytecode);
Функции возвращают true, если выгрузка произошла удачно и false - если возникли ошибки.
save_bytecode, ctpp_save_bytecode
Запись байткода в файл.
$Template-> save_bytecode($Bytecode, "example.ct2");
ctpp_save_bytecode($Template, $Bytecode, "example.ct2");
Функции вставки параметров и вывода
emit_params, ctpp_emit_params
Вставка параметров. На вход принимается массив, состоящий из пар "ключ => значение". При этом в качестве значения может выступать число, строка или массив данных.
$Template-> emit_params(Array("foo" => "bar"));
ctpp_emit_params($Template, Array("foo" => "bar"));
Функции возвращают true, если операция произошла удачно и false - если возникли ошибки.
reset_params, ctpp_reset_params
Очистка ранее введенных параметров.
$Template-> reset_params();
ctpp_reset_params($Template);
Функции возвращают true, если операция произошла удачно и false - если возникли ошибки.
output, ctpp_output
Выполнение байткода и печать результатов.
$Template-> output($Bytecode);
ctpp_output($Template, $Bytecode);
Функции возвращают true, если операция произошла удачно и false - если возникли ошибки.
output_string, ctpp_output_string
Выполнение байткода и Вывод результатов в виде строки.
echo $Template-> output_string($Bytecode);
echo ctpp_output_string($Template, $Bytecode);
Функции возвращают строку результатов полученных при выполнении байткода.
Функции отладки
Для того чтобы убедиться что все данные, переданные в шаблонизатор интерпретированы верно, можно воспользоваться методами ctpp_dump_params(dump_params) и ctpp_dump_params_string(dump_params_string).
dump_params, ctpp_dump_params
Вывод данных в виде, удобном для прочтения.
$Template-> dump_params();
ctpp_dump_params($Template);
dump_params_string, ctpp_dump_params_string
Вывод данных в виде, удобном для прочтения.
echo $Template-> dump_params_string();
echo ctpp_dump_params_string($Template);
Функции возвращают строку c данными в виде, удобном для прочтения.
get_last_error, ctpp_get_last_error
Получение информации об ошибках.
echo $Template-> get_last_error();
echo ctpp_get_last_error($Template);
Функции возвращают массив с информацией о возникшей ошибке.
В массиве определены следующие ключи:
error_code
Числовой код ошибки.
error_str
Текстовое описание ошибки.
template_name
Имя шаблона, где произошла ошибка.
line
Строка шаблона.
pos
Позиция в строке.
ip
Номер инструкции виртуальной машины.
Все ошибки делятся на три типа: ошибки, возникающие во время компиляции шаблона, ошибки работы с данными и ошибки виртуальной машины.
Для каждого типа ошибки определен свой префикс:
| Константа | Значение | Описание | Комментарий |
| Типы ошибок |
| CTPP_ERROR_SUBSYSTEM_MASK | 0xFF000000 | маска типа ошибки | |
| CTPP_DATA_ERROR | 0x01000000 | ошибка данных | |
| CTPP_VM_ERROR | 0x02000000 | ошибка виртуальной машины | |
| CTPP_COMPILER_ERROR | 0x04000000 | ошибка компиляции шаблона | |
| Значения ошибок |
| CTPP_ERROR_CODE_MASK | 0x00FFFFFF | маска кода ошибки | |
| CTPP_OPERATORS_MISMATCH_ERROR | 0x00000012 | ошибка порядка следования операторов | |
| CTPP_SYNTAX_ERROR | 0x00000011 | синтаксическая ошибка | |
| CTPP_PARSER_ERROR | 0x00000010 | ошибка парзера | |
| CTPP_ZERO_DIVISION_ERROR | 0x0000000F | ошибка следования операторов | |
| CTPP_EXECUTION_LIMIT_REACHED_ERROR | 0x0000000E | достигнуто ограничение времени исполнения шаблона | |
| CTPP_CODE_SEGMENT_OVERRUN_ERROR | 0x0000000D | выход за границы сегмента кода | |
| CTPP_INVALID_SYSCALL_ERROR | 0x0000000C | выход за границы сегмента кода | |
| CTPP_ILLEGAL_OPCODE_ERROR | 0x0000000B | неправильная инструкция виртуальной машины | |
| CTPP_STACK_OVERFLOW_ERROR | 0x0000000A | переполнение стека | |
| CTPP_STACK_UNDERFLOW_ERROR | 0x00000009 | попытка чтения из пустого стека | |
| CTPP_VM_GENERIC_ERROR | 0x00000008 | ошибка виртуальной машины CTPP | |
| CTPP_UNIX_ERROR | 0x00000007 | ошибка unix | |
| CTPP_RANGE_ERROR | 0x00000006 | выход за границы массива | |
| CTPP_ACCESS_ERROR | 0x00000005 | неправильный доступ к элементу массива | |
| CTPP_TYPE_CAST_ERROR | 0x00000004 | невозможность приведения типов данных | |
| CTPP_LOGIC_ERROR | 0x00000003 | логическая ошибка | |
| CTPP_UNKNOWN_ERROR | 0x00000002 | неизвестная ошибка CTPP | |
| STL_UNKNOWN_ERROR | 0x00000001 | неизвестная ошибка C++ | |
Если метод вернул FALSE, можно получить содержимое ошибки:
<?php
if (ctpp_output($T, $tmpl) === false)
{
$ErrorDescr = ctpp_get_last_error($T);
printf("Ошибка 0x%08X: %s\n", $ErrorDescr["error_code"],
htmlspecialchars($ErrorDescr["error_str"]));
printf("Файл %s: строка %d, позиция %d\n", $ErrorDescr["template_name"],
$ErrorDescr["line"],
$ErrorDescr["pos"]);
}
?>
|