Разработка расширения для PHP на C++. Хуки встроенных функций и методов08.12.2023 15:00

При запуске проекта, ожидаемо увидим текущую дату. Перейдем непосредственно к реализации логики подмены вызова функции date и вызова наших callback-функций.
В рантайме встроенные функции хранятся в хеш-таблице к которой мы можем легко получить доступ с помощью макроса CG (compiler globals), в случае классов, их методы содержатся в структуре zend_class_entry. Получим указатель на оригинальную функцию или метод класса c помощью функции работы с хеш-таблицами zend_hash_str_find_ptr:

...
auto *original_function = static_cast(zend_hash_str_find_ptr(
        clazz != nullptr ? &clazz->function_table : CG(function_table), function->val,
        function->len));
...

Далее убедимся, что мы что-то нашли и это точно встроенная, а не пользовательская функция, поскольку с пользовательскими функциями такой подход не сработает.

...
if (original_function != nullptr) {
    if (original_function->internal_function.type == ZEND_INTERNAL_FUNCTION) {
    //...
  }
}
...

original_function является указателем на union _zend_function, который в свою очередь содержит поле internal_function типа zend_internal_function, а в нем есть нужный нам zif_handler handler, его то мы и будем подменять на функцию ZEND_NAMED_FUNCTION(my_hook) которую мы объявили выше:

...
original_function->internal_function.handler = my_hook;
...

Запустим проект и теперь увидим, что вместо даты у нас выводится текст «my_hook» и ошибка Fatal error: date (): Return value must be of type string, null returned in Unknown on line 0 поскольку мы изменили обработчик функции, но не ее сигнатуру.

Теперь нам нужно как-то сохранить callback-функции и обработчик оригинальной функции date для их последующего вызова внутри ZEND_NAMED_FUNCTION(my_hook)

Для хранения оригинальных обработчиков и callback-функций напишем собственную структуру, разместим ее в файле php_hooks.h

...
struct hook_t {
    std::string name;

    zend_fcall_info before_fci{};
    zend_fcall_info after_fci{};

    zend_fcall_info_cache before_fcc{};
    zend_fcall_info_cache after_fcc{};

    zif_handler original_handler;
};


ZEND_BEGIN_MODULE_GLOBALS(hooks)
    std::map> *originals;
ZEND_END_MODULE_GLOBALS(hooks)
...

В макросе ZEND_MODULE_GLOBALS мы можем расположить глобальные переменные необходимые для работы нашего модуля, макрос разворачивается в обычную структуру. Это особенно важно если php работает в режиме php-fpm, подмена функции будет действовать на протяжении жизни всего процесса, если такое поведение не требуется, то необходимо либо добавить функцию снятия хука и возвращать оригинальный handler, либо делать это автоматически в PHP_RSHUTDOWN

Для использования переменных объявленных в макросе ZEND_MODULE_GLOBALS в файле hooks.cpp, после подключения заголовочных файлов необходимо добавить вызов макроса

ZEND_DECLARE_MODULE_GLOBALS(hooks)

Кроме этого их необходимо проинициализировать в callback PHP_MINIT_FUNCTION, который инициализируется при загрузке модуля, добавим следующий код в hooks.cpp

...
static void php_init_globals(zend_hooks_globals *ng) {
    ng->originals = new std::map>();
}

PHP_MINIT_FUNCTION (hooks) {
    ZEND_INIT_MODULE_GLOBALS(hooks, php_init_globals, null);
    return SUCCESS;
}
...

Также необходимо не забыть добавить данную функцию инициализации модуля в структуру zend_module_entry, сделать это можно с помощью макроса PHP_MINIT(hooks).

Теперь глобальные переменные будут доступны через hooks_globals, дополним логику функции hooks_set_hook сохранением всех необходимых данных и она примет следующий вид:

PHP_FUNCTION (hooks_set_hook) {
    // Инициализируем необходимые переменные для получения аргементов
    zend_string *function = nullptr;
    zend_class_entry *clazz = nullptr;
    zend_fcall_info before_fci = zend_fcall_info();
    zend_fcall_info after_fci = zend_fcall_info();
    zend_fcall_info_cache before_fcc = zend_fcall_info_cache();
    zend_fcall_info_cache after_fcc = zend_fcall_info_cache();

    // Проверяем соответствует ли текущий вызов одному из двух вариантов
    if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "CSff",
                                 &clazz, &function, &before_fci, &before_fcc, &after_fci, &after_fcc) != SUCCESS and
        zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "Sff",
                                 &function, &before_fci, &before_fcc, &after_fci, &after_fcc) != SUCCESS
            ) {
        // Если мы получили не те аргементы которые ожидали выбросим исключение и вернем false
        zend_throw_exception_ex(spl_ce_InvalidArgumentException, 0, "Invalid arguments");
        RETURN_FALSE;
    }

    // Получим указатель на оригинальную функцию или метод класса
    auto *original_function = static_cast(zend_hash_str_find_ptr(
            clazz != nullptr ? &clazz->function_table : CG(function_table), function->val,
            function->len));
    // Проверим, что мы нашли встроенную функцию
    if (original_function != nullptr) {
        if (original_function->internal_function.type == ZEND_INTERNAL_FUNCTION) {
            // Сформируем ключ для std::map
            std::string key;
            if (clazz) {
                key.append(clazz->name->val);
                key.append("::");
            }
            key.append(function->val);

            //Проверим не установили ли мы хук ранее
            auto original_it = hooks_globals.originals->find(key);
            if (original_it == hooks_globals.originals->end()) {
                //сохраним все, что необходимо в глобальную переменную модуля
                auto hook = std::make_shared();
                hook->name = key;
                hook->before_fci = before_fci;
                hook->after_fci = after_fci;

                hook->before_fcc = before_fcc;
                hook->after_fcc = after_fcc;
                hook->original_handler = original_function->internal_function.handler;
                hooks_globals.originals->insert(std::pair>(key, std::move(hook)));
                original_function->internal_function.handler = my_hook;
                RETURN_TRUE;
            }
        }
    }
    RETURN_FALSE;
}

На этом написание функции установки хуков завершено.

Шаг 7. Реализация выполнения callback функций, перехват аргументов, исключений и результата целевой функции.

Вернемся к функции ZEND_NAMED_FUNCTION(my_hook) и напишем ее реализацию, в эту функцию передается два аргумента по ссылке — zend_execute_data *execute_data и zval *return_value. Первый хранит всю информацию о вызове функции, во второй нужен для возвращаемого значения.
Для начала получим название той функции которая была вызвана и попробуем найти ее среди сохраненных хуков:

...
// название функции или метода
auto function_name = execute_data->func->internal_function.function_name;
std::string key;
// если есть this то имеем дело с методом класса
if (getThis() != nullptr) {
    key.append(execute_data->func->internal_function.scope->name->val);
    key.append("::");
}
key.append(function_name->val);
// проверяем есть ли ключ в таблице, если нет завершаем работу.
auto hook_info = hooks_globals.originals->find(key);
if (hook_info == hooks_globals.originals->end()) {
    return;
}
...

Следующим шагом просто вызовем оригинальную функцию:

...
hook_info->second->original_handler(INTERNAL_FUNCTION_PARAM_PASSTHRU);
...

Теперь можно снова запустить проект и если все сделано верно в терминале мы увидим дату полученную функцией date. Осталось добавить вызовы сохраненных callback-функций до и после оригинальной. Начнем с подготовки аргументов для первой callback-функции, она в качестве аргумента должна принимать имя оригинальной функции и все ее параметры.

...
auto hook_info = hook_info_it->second;

// Массив аргументов для callback-функции, будет содержать ключи name и args
HashTable *handler_args_array;
ALLOC_HASHTABLE(handler_args_array);
zend_hash_init(handler_args_array, 0, NULL, ZVAL_PTR_DTOR, 0);

//Аргументы для callback-функции
zval handler_args_zval[2];
ZVAL_ARR(&handler_args_zval[0], handler_args_array);

// Массив аргументов переданных при вызове оригинальной функции
HashTable *hooked_args_array;
ALLOC_HASHTABLE(hooked_args_array);
zend_hash_init(hooked_args_array, 0, NULL, ZVAL_PTR_DTOR, 0);

zval hooked_args_zval;
ZVAL_ARR(&hooked_args_zval, hooked_args_array);

// копируем переданные аргументы, мы получим именно копию
int arg_count = ZEND_CALL_NUM_ARGS(execute_data);
for (int i = 1; i <= arg_count; i++) {
    zend_hash_next_index_insert(hooked_args_array, ZEND_CALL_ARG(execute_data, i));
}
// подготавливаем массив handler_args_array
zval hook_name;
ZVAL_STRING(&hook_name, key.c_str());
zend_hash_str_add(handler_args_array, "name", 4, &hook_name);
zend_hash_str_add(handler_args_array, "args", 4, &hooked_args_zval);

// Производим вызов первой callback-функции, передавая в качестве аргумента массив
hook_info->before_fci.params = handler_args_zval;
hook_info->before_fci.param_count = 2;
// переменная для сохранения результата работы callback-функции
zval before_ret;
hook_info->before_fci.retval = &before_ret;

zend_call_function(&hook_info->before_fci, &hook_info->before_fcc);
...

Теперь если мы запустим проект, то перед вызовом date будет вызван наш callback. Осталось дело за малым, подготовить аргументы вызова второй callback-функции и вызвать ее. Сохраним результат работы оригинальной функции, проверим есть ли исключение и сохраним его.

...
// Добавим результат работы оригинальной функции в массив аргументов
if (Z_TYPE_P(return_value) != IS_NULL) {
    zend_hash_str_add(handler_args_array, "result", 6, return_value);
}
// проверим есть ли необработанное исключение и если есть сохраним ссылку на него
auto exception = EG(exception);
if (exception != nullptr) {
    zval exception_zval;
    ZVAL_OBJ(&exception_zval, exception);
    zend_hash_str_add(handler_args_array, "exception", 9, &exception_zval);
    zend_exception_save();
}

// Производим вызов второй callback-функции, передавая в качестве аргумента массив
hook_info->after_fci.params = handler_args_zval;
hook_info->after_fci.param_count = 2;
// переменная для сохранения результата работы callback-функции
zval after_ret;
hook_info->after_fci.retval = &after_ret;

zend_call_function(&hook_info->after_fci, &hook_info->after_fcc);

// Восстановим исключение
if (exception != nullptr) {
    zend_exception_restore();
}

//Не забываем освобождать ресурсы
zend_hash_destroy(handler_args_array);
FREE_HASHTABLE(handler_args_array);
...

Вызов zend_exception_save необходим для того, чтобы подавить исключение и продолжить выполнение функции и вызова второго callback, после чего мы восстанавливаем исключение с помощью zend_exception_restore.

Запустим проект еще раз и если все было сделано без ошибок, увидим выполнение оригинальной функции и двух callback-функций.

На этом реализация расширения для php на с++ закончена. Ознакомиться с проектом целиком можно в репозитории на github, ссылка будет в конце статьи.

Шаг 8. Проверка корректной работы модуля

Мы протестировали работу с одной функцией date, но наше расширение должно работать и с методами классов, а также уметь перехватывать исключения, давайте проверим это на примере подключения к не существующей БД SQLite:

getMessage();
};

После запуска получим следующее:

Hidden text

before function called
Array
(
    [name] => PDO::__construct
    [args] => Array
        (
            [0] => sqlite:/database.db
        )

)
after function called
Array
(
    [name] => PDO::__construct
    [args] => Array
        (
            [0] => sqlite:/database.db
        )

    [exception] => PDOException Object
        (
            [message:protected] => SQLSTATE[HY000] [14] unable to open database file
            [string:Exception:private] =>
            [code:protected] => 14
            [file:protected] => /mnt/c/Users/artuk/Desktop/hooks2/test.php
            [line:protected] => 17
            [trace:Exception:private] => Array
                (
                    [0] => Array
                        (
                            [file] => /mnt/c/Users/artuk/Desktop/hooks2/test.php
                            [line] => 17
                            [function] => __construct
                            [class] => PDO
                            [type] => ->
                            [args] => Array
                                (
                                    [0] => sqlite:/database.db
                                )

                        )

                )

            [previous:Exception:private] =>
            [errorInfo] => Array
                (
                    [0] => HY000
                    [1] => 14
                    [2] => unable to open database file
                )

        )

)
Connection failed: SQLSTATE[HY000] [14] unable to open database file
Process finished with exit code 0

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

Заключение

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

В этой статье мы подробно рассмотрели процесс создания расширения для PHP на C++. Начиная с настройки среды разработки и создания проекта, мы последовательно прошли через шаги по реализации хуков и выполнения callback-функций. Мы покрыли ключевые моменты, от встраивания хуков во встроенные PHP-функции до подмены целевых функций и обработки аргументов, исключений и результатов.

Надеюсь эта информация будет вам полезна.

Репозиторий проекта:

https://github.com/ArtUkrainskiy/hooks

Полезные материалы:

https://github.com/php/php-src/ — официальный репозиторий php

https://www.phpinternalsbook.com/ — хороший справочный материал, хоть местами и сильно устарел

© Habrahabr.ru