Декораторы в PHP. Реализация расширения

По результатам опроса в первой статье ^[1], решено было сделать обзор реализации расширения. К этому моменту в угоду существующим IDE немного изменился синтаксис, который, пожалуй, был наиболее обсуждаемым моментом.
Это не еще-одна-статья-о-hello-world-расширении, т.к. желающим разобраться в основах легко найти массу материалов как на ^[2] самом ^[3] Хабре ^[4], так и в русскоязычном ^[5] RTFG ^[6].
Статья о предпосылках, реализации и подводнях камнях. В ней будет мало PHP, в основном C.

Предпосылки

Если не интересно читать tl;dr, то можно сразу перейти к Реализации ^[7].

Декораторы функций (методы не упоминаются здесь и далее, т.к. для декорирования они ничем не отличаются) позволяют изменить работу последних, оборачивая их вызовы дополнительным слоем логики. В декларативной форме описывается список обёрток, которые в итоге должны вернуть нечто, чем будет заменена исходная функция. В python синтаксисе получаем следующее ^[9]:

@decomaker(argA, argB, ...)
def func(arg1, arg2, ...):
    # ...

# Эквивалентно:
func = decomaker(argA, argB, ...)(func)

В PHP такой возможности нет. Сначала я решил взять этот синтаксис как есть и перенести его без изменений (кроме передачи параметров декоратора при вызове; об этом ниже). В первой статье именно такой синтаксис и описывается. Однако IDE с проверкой синтаксиса и один из двух лагерей комментаторов заставили задуматься. В итоге синтаксис сделан более переносимым. Теперь описание декоратора должно описываться в однострочном комментарии #:

• # частично является deprecated, так что его применение будет заметнее обычных //, /* и /**;
• Однострочный комментарий не сворачивается и его тяжелее упустить из виду;
• Вдруг в php 5.x декораторы-таки появятся и необходимость в этом расширении со странным синтаксисом отпадет.

Определившись с форматом описания нужно решить, как сами декораторы будут реализовываться. Функция-декоратор должна возвращать функцию, которая замещает собой исходную декорируемую. Тут как нельзя кстати приходятся анонимные функции и замыкания:

<?php
function decor($func) {
    echo "Decorator!n";
    return function () use($func) {
        return call_user_func_array($func, func_get_args());
    };
}

function a($v)
{
    var_dump($v);
}

$b = decor('a');

$b(42);

/* Вывод:

Decorator!
int(42)
*/

В итоге получается синтаксис с изображения в начале статьи:

<?php
function decor($func) {
    return function(){}
}

# @decor
function original()
{
    // ...
}

И вот это хочется получить без переписывания лексера Zend'а ^[10], чтобы не пришлось пересобирать сам PHP (работает — не трожь).

Реализация

Для выполнения задуманного есть два варианта:

• Менять исходный код до того, как он попадет к лексеру PHP;
• Менять уже готовый opcode, но тогда синтаксис должен быть совместим с существующим.

Второй вариант выглядел сомнительным в вопросе совместимости со всякими opcode кешерами и оптимизаторами. Да и первоначальный вариант синтаксиса декораторов (без # комментария) в этом случае бы не работал.
Выбран был первый вариант.
В Zend есть два источника «поступления» исходного кода:

• Просто строка с кодом (аналог eval): zend_eval_string[l][_ex] ^[11], которые все в итоге сводятся к вызову zend_compile_string ^[12];
• Файл, полученный из разных источников (stdin, stream, etc. Все варианты указаны в перечислении zend_stream_type ^[13]). В этом случае нас интересует zend_compile_file ^[14].

В обоих случаях у нас есть указатели на функции с конкретной реализацией. Стандартные реализации можно найти, посмотрев на инициализацию указателей в zend_startup ^[15]:

• zend_compile_file реализуется в compile_file ^[16];
• zend_compile_string — в столь же очевидной compile_string ^[17].

Обе функции принимают на вход в той или иной форме исходный код и выдают массив opcode'ов в виде структурки _zend_op_array ^[18]. К сожалению, несмотря на схожесть выполняемых задач, реализация у них разная. Так что влиять будем на обе.

Влияние на подобные указатели на функции в Zend и PHP расширениях поставлено на поток. К примеру, та же zend_compile_file подменяется в ZendAccelerator ^[19] и phar ^[20]. Это не считая сторонних расширений.

Для подмены, нужно лишь реализовать свой аналог, и подменить указатель, сохранив оригинал. Всё как всегда.

PHP_MINIT_FUNCTION(decorators);
PHP_MSHUTDOWN_FUNCTION(decorators);

zend_module_entry decorators_module_entry = {
    // ...
    decorators_functions,
    PHP_MINIT(decorators),
    PHP_MSHUTDOWN(decorators),
    // ...
};

zend_op_array *(*decorators_orig_zend_compile_string)(zval *source_string, char *filename TSRMLS_DC);
zend_op_array *(*decorators_orig_zend_compile_file)(zend_file_handle *file_handle, int type TSRMLS_DC);

zend_op_array* decorators_zend_compile_string(zval *source_string, char *filename TSRMLS_DC);
zend_op_array* decorators_zend_compile_file(zend_file_handle *file_handle, int type TSRMLS_DC);

/* {{{ PHP_MINIT_FUNCTION
 */
PHP_MINIT_FUNCTION(decorators)
{
    decorators_orig_zend_compile_string = zend_compile_string;
    zend_compile_string                 = decorators_zend_compile_string;

    decorators_orig_zend_compile_file = zend_compile_file;
    zend_compile_file                 = decorators_zend_compile_file;

    return SUCCESS;
}
/* }}} */

/* {{{ PHP_MSHUTDOWN_FUNCTION
 */
PHP_MSHUTDOWN_FUNCTION(decorators)
{
    zend_compile_string = decorators_orig_zend_compile_string;

    zend_compile_file = decorators_orig_zend_compile_file;

    return SUCCESS;
}
/* }}} */

zend_op_array* decorators_zend_compile_string(zval *source_string, char *filename TSRMLS_DC) /* {{{ */
{
    return decorators_orig_zend_compile_string(source_string, filename TSRMLS_CC);
}
/* }}} */

zend_op_array* decorators_zend_compile_file(zend_file_handle *file_handle, int type TSRMLS_DC) /* {{{ */
{
    return decorators_orig_zend_compile_file(file_handle, type TSRMLS_CC);
}
/* }}} */

При инициализации модуля (нашего расширения) подменили указатели, при завершении работы не забыли всё вернуть. Непосредственно в подменённых функциях вызываем оригинальные реализации.
Не всё можно делать при инициализации модуля, но в нашем случае этого вполне достаточно.

И если с compile_string все более-менее ясно (на вход приходит исходная строка), то вот с compile_file не все так радужно — исходника-то у нас нет, только описание источника в zend_file_handle ^[21]. Причем в разных случаях используются разные наборы полей.

ZEND_API zend_op_array *compile_file(zend_file_handle *file_handle, int type TSRMLS_DC)
{
    // ...
    open_file_for_scanning(file_handle TSRMLS_CC)
    // ...
}

ZEND_API int open_file_for_scanning(zend_file_handle *file_handle TSRMLS_DC)
{
    // ...
    zend_stream_fixup(file_handle, &buf, &size TSRMLS_CC)
    // ...
}

И самое интересное тут для нас — zend_stream_fixup ^[22], функция, которая унифицирует все источники поступления исходного кода и выдает на выходе считанный буфер и его размер. Вот вроде бы то, что нам нужно, но повлиять на работу zend_stream_fixup и open_file_for_scanning мы не можем, у нас есть контроль только над compile_file. Кто-то пошел копипастить к себе эти функции и все их зависимости, но мы сделаем проще. Если посмотреть на исходник zend_stream_fixup, то видно, что все типы сводятся в итоге к единому ZEND_HANDLE_MAPPED, у которого в file_handle->handle.stream.mmap.buf и file_handle->handle.stream.mmap.len содержится исходный код и его длина соответственно. Причем, если в file_handle уже указан этот тип данных, то практически ничего уже менять не надо и всё выдается как есть.
Выходит, если мы передадим в compile_file() zend_file_handle *file_handle уже в формате ZEND_HANDLE_MAPPED с корректным значением всех полей, то compile_file это примет как так и было. А сделать это мы может вызвав zend_stream_fixup (которая является функцией Zend API, а не подменяемым указателем) еще разок до вызова compile_file. Тогда повторный вызов внутри open_file_for_scanning просто ничего не изменит.

zend_op_array* decorators_zend_compile_file(zend_file_handle *file_handle, int type TSRMLS_DC) /* {{{ */
{
    char *buf;
    size_t size;

    if (zend_stream_fixup(file_handle, &buf, &size TSRMLS_CC) == FAILURE) {
        return NULL;
    }
    // теперь в file_handle у нас гарантированно ZEND_HANDLE_MAPPED

    return decorators_orig_zend_compile_file(file_handle, type TSRMLS_CC);
}
/* }}} */

Ура, работает. Более того, у нас в file_handle->handle.stream.mmap.buf/len содержится исходник, откуда бы PHP его не взял: stdin, fd, include http stream… Осталось положить туда наш измененный вариант кода и вызвать оригинальную zend_compile_file.

Как работает decorators_preprocessor() писать не буду: очевидное получение строки, ее передача препроцессору и отдача результирующей строки. Ниже и так будут куски кода из этой функции.

Осталось рассмотреть сам препроцессор.

void preprocessor(zval *source_zv, zval *return_value TSRMLS_DC)
{
    // Из исходной строки source_zv формирую строку в return_value
}

/* {{{ DECORS_CALL_PREPROCESS */
#define DECORS_CALL_PREPROCESS(result_zv, buf, len)   
    do {                                              
        zval *source_zv;                              
        ALLOC_INIT_ZVAL(result_zv);                   
        ALLOC_INIT_ZVAL(source_zv);                   
        ZVAL_STRINGL(source_zv, (buf), (len), 1);     
        preprocessor(source_zv, result_zv TSRMLS_CC); 
        zval_dtor(source_zv);                         
        FREE_ZVAL(source_zv);                         
    } while (0);                                      
/* }}} */

/* {{{ proto string decorators_preprocessor(string $code)
*/
PHP_FUNCTION(decorators_preprocessor)
{
    char *source;
    int source_len;
    zval *result;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &source, &source_len) == FAILURE) {
        return;
    }
    DECORS_CALL_PREPROCESS(result, source, source_len);
    // ...
}
/* }}} */

zend_op_array* decorators_zend_compile_string(zval *source_string, char *filename TSRMLS_DC) /* {{{ */
{
    zval *result;
    DECORS_CALL_PREPROCESS(result, Z_STRVAL_P(source_string), Z_STRLEN_P(source_string));
    // ...
}
/* }}} */

zend_op_array* decorators_zend_compile_file(zend_file_handle *file_handle, int type TSRMLS_DC) /* {{{ */
{
    // ...
    zval *result;
    DECORS_CALL_PREPROCESS(result, file_handle->handle.stream.mmap.buf, file_handle->handle.stream.mmap.len);
    // ...
}
/* }}} */

Найти и переделать!

Задача препроцессора — найти описания декораторов и модифицировать код функций, на которые декораторы влияют. А для этого лучше всего работать с токенами исходного текста. Чтобы не изобретать велосипед, был использован родной Zend'овский лексический сканер lex_scan ^[23], пример использования которого в своих целях можно посмотреть в реализации token_get_all ^[24] и tokenize ^[25], вызываемой внутри token_get_all.

1. Сохраняем текущее окружение сканера, в котором работает наш код:
   

   zend_lex_state original_lex_state;
   zend_save_lexical_state(&original_lex_state TSRMLS_CC);

2. Подготавливаем исходную строку к парсингу:
   

   zend_prepare_string_for_scanning(&source_z, "" TSRMLS_CC)

3. Задаем начальное состояние лексера (все варианты тут ^[26]):
   

   LANG_SCNG(yy_state) = yycST_IN_SCRIPTING;

   В отличие от token_get_all мы парсим уже PHP код, так что наличие открывающего тега нам не обязательно. Соотвественно, начальное состояние у нас не yycINITIAL, а yycST_IN_SCRIPTING.

4. В цикле получаем все лексемы исходной строки:
   

   zval token_zv;
   int token_type;
   while (token_type = lex_scan(&token_zv TSRMLS_CC)) {
   //…
   }

   token_type — тип лексемы:

   • <256 — код символа односимвольной лексемы;
   • >= 256 — значение константы T_* ^[27]. Строковое описание по token_type можно получить через PHP_FUNCTION(token_name)/get_token_type_name.

   token_zv содержит само значение лексемы. Однако, в качестве альтернативы можно использовать поля yy_text и yy_leng структуры zend_lex_state ^[28], хранящие адрес первого байта текущей лексемы и её длину соотвественно. Доступ к этим полям, как и многое в Zend, реализуется через соответствующие макросы:

   #define zendtext LANG_SCNG(yy_text)
   #define zendleng LANG_SCNG(yy_leng)

   Теперь пользуемся char* zendtext и unsigned int zendleng.

   Чтобы не было memory leak'ов нужно учитывать, что значение token_zv иногда берется как есть из исходного буфера, а иногда под него выделяется память. Которую нужно освобождать. Интересующиеся могут посмотреть код lex_scan(), а сейчас просто возьмем необходимый кусок логики из token_get_all.

5. Восстанавливаем окружение сканера, в котором работает наш код:
   

   zend_restore_lexical_state(&original_lex_state TSRMLS_CC);

Всё, у нас есть лексический разбор исходного кода. Но хотелось бы осветить еще некоторые моменты парсинга.

При ошибках разбора PHP обработчик генерит ошибку или исключение, имя файла и номер строки в тексте которых берутся из состояния _zend_compiler_globals ^[29]. Имя файла, например, берётся из поля compiled_filename. Которое задается при вызове zend_prepare_string_for_scanning(). А используется внутри zend_error ^[30] (используемая для генерации всякие E_* ошибок; она же используется и в этом расширении для генерации E_PARSE). Но compiled_filename в zend_error() используется только если Zend находится в состоянии компилирования (zend_bool in_compilation; всё в том же _zend_compiler_globals). Который сам по себе не активируется, если мы парсим исходник.
Так что перед парсингом мы переключаемся на «компилирование»:

zend_bool original_in_compilation = CG(in_compilation);
CG(in_compilation) = 1;

А по окончанию возвращаем всё обратно:

CG(in_compilation) = original_in_compilation;

Теперь, если мы передадим в zend_prepare_string_for_scanning корректный filename, то возможные ошибки будут гораздо информативней. Получить текущее имя файла можно через zend_get_compiled_filename(), который, правда, может вернуть NULL, от которого php (если NULL передать в zend_prepare_string_for_scanning) упадет в segfault.

PHP_FUNCTION(decorators_preprocessor)
{
    // ...
    char *prev_filename = zend_get_compiled_filename(TSRMLS_CC) ? zend_get_compiled_filename(TSRMLS_CC) : "";
    zend_set_compiled_filename("-" TSRMLS_CC);

    DECORS_CALL_PREPROCESS(result, source, source_len);

    zend_set_compiled_filename(prev_filename TSRMLS_CC);
    // ...
}

zend_op_array* decorators_zend_compile_file(zend_file_handle *file_handle, int type TSRMLS_DC) /* {{{ */
{
    // ...
    char *prev_filename = zend_get_compiled_filename(TSRMLS_CC) ? zend_get_compiled_filename(TSRMLS_CC) : "";
    const char* filename = (file_handle->opened_path) ? file_handle->opened_path : file_handle->filename;
    zend_set_compiled_filename(filename TSRMLS_CC);

    zval *result;
    DECORS_CALL_PREPROCESS(result, file_handle->handle.stream.mmap.buf, file_handle->handle.stream.mmap.len);

    zend_set_compiled_filename(prev_filename TSRMLS_CC);
    // ...
}

Модификация исходного кода

Получив всё, что нужно для препроцессинга, осталось его собственно и произвести. Задача в переводе текста, составленного из кусков (лексем) в итоговый текст могла бы быть не так проста в C из-за активной работы со склейкой строк. Однако, в /PHP/ext/standard/php_smart_str.h ^[31] есть реализация smart строк, которые нам очень пригодятся.

    smart_str str = {0};
    smart_str str2 = {0};
    smart_str_appendc(&str, '!');
    smart_str_appendl(&str, "hello", 5);
    smart_str_append(&str, &str2);
    smart_str_append_long(&str, 42);
    // и т.д.
    // результирующая строка длиной size_t str.len может быть получена через char* str.c
    // освобождение памяти:
    smart_str_free(&result);

В цикле разбора лексем клеим результирующую строку из лексем (zendtext, zendleng), где нужно меняя/добавляя от себя. Непосредственно алгоритм замены декораторов, имхо, не столь интересен. Из потенциально интересного — проверка, что лексема типа T_COMMENT похожа на описание декоратора: идет проверка регулярки '^#[ t]*@' (простым циклом, без regexp) и возвращается адрес '@'.

Немного PHP напоследок

При обработке декораторов немного меняется исходный код декорируемой функции: тело функции заворачивается в анонимную функцию, которая передается параметром ближайшему декоратору. Т.е. для кода

// comment
@a(A)
@b
@c(C, D)
/**
 * yet another comment
 */
function x(X)
{
    Y
}

в результате препроцессинга получится следующий код:

// comment



/**
 * yet another comment
 */
function x(X)
{ return call_user_func_array(a(b(c(function(X) {
    Y
}, C, D)), A), func_get_args());}

Под A, C, D, X подразумевается произвольный код, который копируется as is.
Из этого вытекают следующие последствия:

• Если декорируемая функция объявлена с параметрами, имеющими значение по умолчанию, то в анонимной функции всё будет также:
  

  function foo($a, $b=42, $c=array(100, 500))
  {…
  =>
  function foo($a, $b=42, $c=array(100, 500))
  { return call_user_func_array(...(function($a, $b=42, $c=array(100, 500)) {…

• При ошибках в описании имен декораторов, строкой кода при описании ошибки будет строка с открывающей тело функции '{'. Аналогично с параметрами декораторов — они будут на строке с закрывающей тело функции '}';
• Параметрам декораторов можно задавать имена переменных декорируемой функции. Получается read/write контроль над параметрами;
• Т.к. для передачи параметров используется func_get_args(), то передача параметра по ссылке в декорируемую функцию в данный момент не работает.

Ну вот и всё. Если вы и правда до сюда дочитали, то, надеюсь, было интересно.

Приведу и в этой статье ссылку на github ^[32].

Автор: AterCattus

Источник ^[33]