antonio's blog

antonio's blog


Блог о всяком разном, связанном с разработкой ПО. Пишу редко, когда есть время и желание.

Anton Dobkin
Author

Share


Tags


Создание PHP расширения

Anton DobkinAnton Dobkin

Есть две основные причины для написания расширения для PHP:

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

Примеры кода, которые будут приведены в данном посте будут работать с PHP 5.3.x - 5.5.x. Скорее всего они будут работать с более поздними версиями.

Для создания расширения нам понадобится:

Создание скелета расширения

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

В системе у меня установлен PHP версии 5.4.x, используем исходные тексты соответствующей версии:

git clone https://github.com/php/php-src.git  
git branch 5.4 origin/PHP-5.4  
git checkout 5.4  

Все расширения находятся в подкаталоге ext каталога с исходными текстами. Каждое расширение имеет свой собственный подкаталог. Cкрипт ext_skel также находится в каталоге ext.

Переходим в каталог с расширениями:

cd php-src/ext  

Использование скрипта ext_skel:

./ext_skel --extname=module [--proto=file] [--stubs=file] [--xml[=file]]
           [--skel=dir] [--full-xml] [--no-help]

--extname=module   module is the name of your extension
--proto=file       file contains prototypes of functions to create
--stubs=file       generate only function stubs in file
--xml              generate xml documentation to be added to phpdoc-cvs
--skel=dir         path to the skeleton directory
--full-xml         generate xml documentation for a self-contained extension
                     (not yet implemented)
--no-help          don't try to be nice and create comments in the code
                     and helper functions to test if the module compiled

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

Создадим файл с прототипами функций:

touch test_extension.def  

Каждая функция в файле - одна строка. Пример описания функции:

test_funct1(string str = "World!")  

При описание функции мы указываем:

если у функции есть аргументы, то:

Аргументы мы можем указать как необязательные. Для этого их необходимо обрамить скобками [ ]. Типы данных - это PHP типы, такие как int, bool, array, float и т.д.

Формат: [тип_возвращаемых_данных] название_функции(тип_данных название_аргумента [=значение_по_умолчанию] [,необязательный_аргумент_1 [, необязательный_аргумент_2]])

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

Итак опишем функции нашего расширения, открываем в текстовом редакторе файл test_extension.def и опишем три функции:

test_funct1()  
string test_funct2(string str = "World")  
int test_funct3(int a [, int b])  

Выполним скрипт ext_skel:

./ext_skel --extname='test_extension' --proto=./test_extension.def

Структура расширения

После того как скрипт отработает, у нас в каталоге ext появится директория, название которой совпадает с нашим расширением, в нашем случае - test_extension. Каталог расширения будет содержать как минимум следующие файлы:

Помимо указанных файлов в каталоге расширения будут еще и другие файлы: .svnignore, EXPERIMENTAL, CREDITS и каталог с тестами tests. Эти файлы пока нас не интересуют

Файла config.m4

Откроем и отредактируем файл config.m4. Так как у нас простое расширение, которое не требует внешних библиотек и заголовочных файлов, то достаточно добавить поддержку опции --enable-test_extension. В файле config.m4 найдем и расскоментируем следующие строки:

dnl PHP_ARG_ENABLE(test_extension, whether to enable test_extension support,  
dnl [  --enable-test_extension           Enable test_extension support])  

комментарий начинается с dnl:

PHP_ARG_ENABLE(test_extension, whether to enable test_extension support,  
[  --enable-test_extension           Enable test_extension support])

Файла php_test_extension.h

Далее откроем и посмотрим код файла php_test_extension.h:

/*
  +----------------------------------------------------------------------+
  | PHP Version 5                                                        |
  +----------------------------------------------------------------------+
  | Copyright (c) 1997-2013 The PHP Group                                |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | http://www.php.net/license/3_01.txt                                  |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Author:                                                              |
  +----------------------------------------------------------------------+
*/

/* $Id$ */

#ifndef PHP_TEST_EXTENSION_H
#define PHP_TEST_EXTENSION_H

extern zend_module_entry test_extension_module_entry;  
#define phpext_test_extension_ptr &test_extension_module_entry

#ifdef PHP_WIN32
#   define PHP_TEST_EXTENSION_API __declspec(dllexport)
#elif defined(__GNUC__) && __GNUC__ >= 4
#   define PHP_TEST_EXTENSION_API __attribute__ ((visibility("default")))
#else
#   define PHP_TEST_EXTENSION_API
#endif

#ifdef ZTS
#include "TSRM.h"
#endif

PHP_MINIT_FUNCTION(test_extension);  
PHP_MSHUTDOWN_FUNCTION(test_extension);  
PHP_RINIT_FUNCTION(test_extension);  
PHP_RSHUTDOWN_FUNCTION(test_extension);  
PHP_MINFO_FUNCTION(test_extension);

PHP_FUNCTION(confirm_test_extension_compiled);  /* For testing, remove later. */  
PHP_FUNCTION(test_funct1);  
PHP_FUNCTION(test_funct2);  
PHP_FUNCTION(test_funct3);

/* 
    Declare any global variables you may need between the BEGIN
    and END macros here:     

ZEND_BEGIN_MODULE_GLOBALS(test_extension)  
    long  global_value;
    char *global_string;
ZEND_END_MODULE_GLOBALS(test_extension)  
*/

/* In every utility function you add that needs to use variables 
   in php_test_extension_globals, call TSRMLS_FETCH(); after declaring other 
   variables used by that function, or better yet, pass in TSRMLS_CC
   after the last function argument and declare your utility function
   with TSRMLS_DC after the last declared argument.  Always refer to
   the globals in your function as TEST_EXTENSION_G(variable).  You are 
   encouraged to rename these macros something shorter, see
   examples in any other php module directory.
*/

#ifdef ZTS
#define TEST_EXTENSION_G(v) TSRMG(test_extension_globals_id, zend_test_extension_globals *, v)
#else
#define TEST_EXTENSION_G(v) (test_extension_globals.v)
#endif

#endif  /* PHP_TEST_EXTENSION_H */

В самом начале объявляется переменная test_extension_module_entry с типом zend_module_entry. zend_module_entry - это структура описывающая расширение. К ней вернемся чуть позже.

Следом за переменной test_extension_module_entry объявляется указатель на эту переменную: phpext_test_extension_ptr

Затем объявляется константа PHP_TEST_EXTENSION_API значение которой зависит от платформы. Данная константа используется для экспорта функций.

Если объявлена переменная ZTS, то происходит подключение заголовочного файла TSRM.h. ZTS - Zend Thread Safety, о мультипоточности поговорим в следующий раз.

Далее идет объявление прототипов функций. Сначала идут прототипы функций относящиеся к жизненному циклу расширения:

PHP_MINIT_FUNCTION(test_extension);  
PHP_MSHUTDOWN_FUNCTION(test_extension);  
PHP_RINIT_FUNCTION(test_extension);  
PHP_RSHUTDOWN_FUNCTION(test_extension);  
PHP_MINFO_FUNCTION(test_extension);  

PHP_*_FUNCTION - это макросы препроцессора, с их помощью будут созданы правильные прототипы, включающие нужные аргументы. В макросы передается название расширения. Так, например, на стадии препроцессора объявление PHP_MINIT_FUNCTION(test_extension) будет развернуто в:

int zm_startup_test_extension(int type, int module_number TSRMLS_DC)  

Более подробнее о жизненом цикле расширения в следующем посте (я надеюсь :))

После объявления функций жизненного цикла идет объявление функций расширения, функции, которые будут доступны в пользовательском пространстве PHP:

PHP_FUNCTION(confirm_test_extension_compiled);  /* For testing, remove later. */  
PHP_FUNCTION(test_funct1);  
PHP_FUNCTION(test_funct2);  
PHP_FUNCTION(test_funct3);  

Функции объявляются с помощью макроса PHP_FUNCTION, в макрос передается название функции, под этим названием функция будет видна в пользовательском пространстве.

Вы наверное обратили внимание на объявление функции confirm_test_extension_compiled, это функция проверки расширения, которую создал скрипт ext_skel. Эту функцию можно смело удалить.

Для примера, объявление PHP_FUNCTION(test_funct1) будет развернуто при сборке в:

zif_test_funct1(int ht, zval *return_value, zval **return_value_ptr, zval *this_ptr, int return_value_used TSRMLS_DC)  

Все функции, конечно, можно описать и без использования макросов, но если API расширений изменится в будущих версиях, например, изменятся аргументы функций, то наш модуль перестанет собираться. Поэтому всегда используйте макросы, предоставляемые PHP API для объявления функций.

Оставшийся код в файле php_test_extension.h пока рассматривать не будем, этот код относится к глобальным переменным и мультипоточности

Файл test_extension.c

Откроем и посмотрим код файла test_extension.с:

/*
  +----------------------------------------------------------------------+
  | PHP Version 5                                                        |
  +----------------------------------------------------------------------+
  | Copyright (c) 1997-2013 The PHP Group                                |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | http://www.php.net/license/3_01.txt                                  |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Author:                                                              |
  +----------------------------------------------------------------------+
*/

/* $Id$ */

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include "php.h"
#include "php_ini.h"
#include "ext/standard/info.h"
#include "php_test_extension.h"

/* If you declare any globals in php_test_extension.h uncomment this:
ZEND_DECLARE_MODULE_GLOBALS(test_extension)  
*/

/* True global resources - no need for thread safety here */
static int le_test_extension;

/* test_extension_functions[]
 *
 * Every user visible function must have an entry in test_extension_functions[].
 */
const zend_function_entry test_extension_functions[] = {  
    PHP_FE(confirm_test_extension_compiled, NULL)       /* For testing, remove later. */
    PHP_FE(test_funct1, NULL)
    PHP_FE(test_funct2, NULL)
    PHP_FE(test_funct3, NULL)
    PHP_FE_END  /* Must be the last line in test_extension_functions[] */
};

/* test_extension_module_entry
 */
zend_module_entry test_extension_module_entry = {  
#if ZEND_MODULE_API_NO >= 20010901
    STANDARD_MODULE_HEADER,
#endif
    "test_extension",
    test_extension_functions,
    PHP_MINIT(test_extension),
    PHP_MSHUTDOWN(test_extension),
    PHP_RINIT(test_extension),      /* Replace with NULL if there's nothing to do at request start */
    PHP_RSHUTDOWN(test_extension),  /* Replace with NULL if there's nothing to do at request end */
    PHP_MINFO(test_extension),
#if ZEND_MODULE_API_NO >= 20010901
    "0.1", /* Replace with version number for your extension */
#endif
    STANDARD_MODULE_PROPERTIES
};

#ifdef COMPILE_DL_TEST_EXTENSION
ZEND_GET_MODULE(test_extension)  
#endif

/*  PHP_INI
 */
/* Remove comments and fill if you need to have entries in php.ini
PHP_INI_BEGIN()  
    STD_PHP_INI_ENTRY("test_extension.global_value",      "42", PHP_INI_ALL, OnUpdateLong, global_value, zend_test_extension_globals, test_extension_globals)
    STD_PHP_INI_ENTRY("test_extension.global_string", "foobar", PHP_INI_ALL, OnUpdateString, global_string, zend_test_extension_globals, test_extension_globals)
PHP_INI_END()  
*/

/*  php_test_extension_init_globals
 */
/* Uncomment this function if you have INI entries
static void php_test_extension_init_globals(zend_test_extension_globals *test_extension_globals)  
{
    test_extension_globals->global_value = 0;
    test_extension_globals->global_string = NULL;
}
*/

/*  PHP_MINIT_FUNCTION
 */
PHP_MINIT_FUNCTION(test_extension)  
{
    /* If you have INI entries, uncomment these lines 
    REGISTER_INI_ENTRIES();
    */
    return SUCCESS;
}

/* PHP_MSHUTDOWN_FUNCTION
 */
PHP_MSHUTDOWN_FUNCTION(test_extension)  
{
    /* uncomment this line if you have INI entries
    UNREGISTER_INI_ENTRIES();
    */
    return SUCCESS;
}

/* Remove if there's nothing to do at request start */
/* PHP_RINIT_FUNCTION
 */
PHP_RINIT_FUNCTION(test_extension)  
{
    return SUCCESS;
}

/* Remove if there's nothing to do at request end */
/* PHP_RSHUTDOWN_FUNCTION
 */
PHP_RSHUTDOWN_FUNCTION(test_extension)  
{
    return SUCCESS;
}

/* PHP_MINFO_FUNCTION
 */
PHP_MINFO_FUNCTION(test_extension)  
{
    php_info_print_table_start();
    php_info_print_table_header(2, "test_extension support", "enabled");
    php_info_print_table_end();

    /* Remove comments if you have entries in php.ini
    DISPLAY_INI_ENTRIES();
    */
}

/* Remove the following function when you have succesfully modified config.m4
   so that your module can be compiled into PHP, it exists only for testing
   purposes. */

/* Every user-visible function in PHP should document itself in the source */
/*  proto string confirm_test_extension_compiled(string arg)
   Return a string to confirm that the module is compiled in */
PHP_FUNCTION(confirm_test_extension_compiled)  
{
    char *arg = NULL;
    int arg_len, len;
    char *strg;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &arg, &arg_len) == FAILURE) {
        return;
    }

    len = spprintf(&strg, 0, "Congratulations! You have successfully modified ext/%.78s/config.m4. Module %.78s is now compiled into PHP.", "test_extension", arg);
    RETURN_STRINGL(strg, len, 0);
}

/* The previous line is meant for vim and emacs, so it can correctly fold and 
   unfold functions in source code. See the corresponding marks just before 
   function definition, where the functions purpose is also documented. Please 
   follow this convention for the convenience of others editing your code.
*/

/* proto  test_funct1()
    */
PHP_FUNCTION(test_funct1)  
{
    if (zend_parse_parameters_none() == FAILURE) {
        return;
    }
    php_error(E_WARNING, "test_funct1: not yet implemented");
}

/* proto string test_funct2(string str)
   = "World") */
PHP_FUNCTION(test_funct2)  
{
    char *str = NULL;
    int argc = ZEND_NUM_ARGS();
    int str_len;

    if (zend_parse_parameters(argc TSRMLS_CC, "s", &str, &str_len) == FAILURE) 
        return;

    php_error(E_WARNING, "test_funct2: not yet implemented");
}

/* proto int test_funct3(int a [, int b])
    */
PHP_FUNCTION(test_funct3)  
{
    int argc = ZEND_NUM_ARGS();
    long a;
    long b;

    if (zend_parse_parameters(argc TSRMLS_CC, "l|l", &a, &b) == FAILURE) 
        return;

    php_error(E_WARNING, "test_funct3: not yet implemented");
}

В самом начале подключаются нужные заголовочные файлы. Затем идет закомментированный блок, относящийся к глобальным переменным:

/* If you declare any globals in php_test_extension.h uncomment this:
ZEND_DECLARE_MODULE_GLOBALS(test_extension)  
*/

Так как сейчас с глобальными переменными мы в нашем расширении не работаем, поэтому оставляем этот код до лучших времен.

Далее идет объявление переменной ресурса:

/* True global resources - no need for thread safety here */
static int le_test_extension;  

Далее идет массив структур zend_function_entry, каждая структура - это информация о функции доступной в пользовательском пространстве.

/*  test_extension_functions[]
 *
 * Every user visible function must have an entry in test_extension_functions[].
 */
const zend_function_entry test_extension_functions[] = {  
    PHP_FE(confirm_test_extension_compiled, NULL)       /* For testing, remove later. */
    PHP_FE(test_funct1, NULL)
    PHP_FE(test_funct2, NULL)
    PHP_FE(test_funct3, NULL)
    PHP_FE_END  /* Must be the last line in test_extension_functions[] */
};

Для создания структуры используется макрос PHP_FE. В макрос передается название функции и структура, описывающая аргументы функции, мы пока передаем NULL.

Далее идет инициализация структуры с информацией о расширении:

zend_module_entry test_extension_module_entry = {  
#if ZEND_MODULE_API_NO >= 20010901
    STANDARD_MODULE_HEADER,
#endif
    // название расширения
    "test_extension",   
    // массив структур с описанием функций доступных в пользовательском пространстве             
    test_extension_functions,  
    // Функция которая будет вызвана при загрузке расширения или NULL  
    PHP_MINIT(test_extension),
    // Функция которая будет вызвана при вызагрузке расширения или NULL      
    PHP_MSHUTDOWN(test_extension),  
    // Функция которая будет вызвана при поступлении нового запроса или NULL
    PHP_RINIT(test_extension),  
    // Функция которая будет вызвана по окончанию обработки поступившего запроса или NULL    
    PHP_RSHUTDOWN(test_extension),  
    // Функция формирующая информацию о расширении
    PHP_MINFO(test_extension),    
#if ZEND_MODULE_API_NO >= 20010901
    // Версия расширения
    "0.1",                          
#endif
    STANDARD_MODULE_PROPERTIES
};

Структура zend_module_entry имеет следующие объявление:

typedef struct _zend_module_entry zend_module_entry;  
struct _zend_module_entry {  
    unsigned short size;   
    unsigned int zend_api;        
    unsigned char zend_debug;
    unsigned char zts;
    const struct _zend_ini_entry *ini_entry;
    const struct _zend_module_dep *deps;
    const char *name;               
    const struct _zend_function_entry *functions;   
    int (*module_startup_func)(INIT_FUNC_ARGS);
    int (*module_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    int (*request_startup_func)(INIT_FUNC_ARGS);
    int (*request_shutdown_func)(SHUTDOWN_FUNC_ARGS);
    void (*info_func)(ZEND_MODULE_INFO_FUNC_ARGS);
    const char *version;                                
    size_t globals_size;
#ifdef ZTS
    ts_rsrc_id* globals_id_ptr;
#else
    void* globals_ptr;
#endif
    void (*globals_ctor)(void *global TSRMLS_DC);
    void (*globals_dtor)(void *global TSRMLS_DC);
    int (*post_deactivate_func)(void);
    int module_started;
    unsigned char type;
    void *handle;
    int module_number;
    char *build_id;
};

Первые шесть полей мы не инициализируем вручную, мы вызываем макрос STANDARD_MODULE_HEADER. Затем указываем функции жизненного цикла расширения, функцию информации о расширении и версию расширения. Для инициализации оставшихся полей структуры мы используем макрос STANDARD_MODULE_PROPERTIES

Следующий блок кода, до PHP_MINIT_FUNCTION(test_extension) относится к глобальным переменным и INI параметрам. Пропускаем

Оставшийся код - реализация функций. Сначала идет реализация функций жизненного цикла расширения:

PHP_MINIT_FUNCTION(test_extension)  
{
    /* If you have INI entries, uncomment these lines 
    REGISTER_INI_ENTRIES();
    */
    return SUCCESS;
}

PHP_MSHUTDOWN_FUNCTION(test_extension)  
{
    /* uncomment this line if you have INI entries
    UNREGISTER_INI_ENTRIES();
    */
    return SUCCESS;
}

/* Remove if there's nothing to do at request start */

PHP_RINIT_FUNCTION(test_extension)  
{
    return SUCCESS;
}

/* Remove if there's nothing to do at request end */
PHP_RSHUTDOWN_FUNCTION(test_extension)  
{
    return SUCCESS;
}

В нашем расширении эти функции ничего полезного не делают. Все функции возвращают значение макроса SUCCESS, которое приравнивается к "успеху".

Затем идет реализация функции информации о расширении:

PHP_MINFO_FUNCTION(test_extension)  
{
    php_info_print_table_start();
    php_info_print_table_header(2, "test_extension support", "enabled");
    php_info_print_table_end();

    /* Remove comments if you have entries in php.ini
    DISPLAY_INI_ENTRIES();
    */
}

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

PHP_FUNCTION(confirm_test_extension_compiled)  
{
    char *arg = NULL;
    int arg_len, len;
    char *strg;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &arg, &arg_len) == FAILURE) {
        return;
    }

    len = spprintf(&strg, 0, "Congratulations! You have successfully modified ext/%.78s/config.m4. Module %.78s is now compiled into PHP.", "test_extension", arg);
    RETURN_STRINGL(strg, len, 0);
}

PHP_FUNCTION(test_funct1)  
{
    if (zend_parse_parameters_none() == FAILURE) {
        return;
    }
    php_error(E_WARNING, "test_funct1: not yet implemented");
}

PHP_FUNCTION(test_funct2)  
{
    char *str = NULL;
    int argc = ZEND_NUM_ARGS();
    int str_len;

    if (zend_parse_parameters(argc TSRMLS_CC, "s", &str, &str_len) == FAILURE) 
        return;

    php_error(E_WARNING, "test_funct2: not yet implemented");
}

PHP_FUNCTION(test_funct3)  
{
    int argc = ZEND_NUM_ARGS();
    long a;
    long b;

    if (zend_parse_parameters(argc TSRMLS_CC, "l|l", &a, &b) == FAILURE) 
        return;

    php_error(E_WARNING, "test_funct3: not yet implemented");
}

Компиляция и установка расширения

Вот и дошли до сборки и проверки нашего тестового расширения. Переходим в каталог расширения:

cd php-src/ext/test_extension  

И выполняем команду phpize:

phpize  

После выполнения этой команды, на основе содержимого файла config.m4, будут созданы файлы необходимые для конфигурации и компиляции расширения: скрипт configure и Makefile.

Конфигурируем и компилируем расширение:

./configure --enable-test_extension
make  

Если сборка завершилась успешно, то вы увидите запись 'Build complete.'

Командой:

sudo make install  

копируем скомпилированное расширение в каталог расширений PHP

Проверка расширения

После установки расширения необходимо сказать PHP, что бы он загружал наш модуль. В файле php.ini, у меня он расположен в каталоге /etc, добавим запись

extension=test_extension.so  

и выполним скрипт test_extension.php, который находится в папке нашего расширения:

php test_extension.php  

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

Functions available in the test extension:  
confirm_test_extension_compiled  
test_funct1  
test_funct2  
test_funct3

Congratulations! You have successfully modified ext/test_extension/config.m4. Module test_extension is now compiled into PHP.  

Надпись "Congratulations! You have successfully modified ext/testextension/config.m4. Module testextension is now compiled into PHP." Формируется и возвращается функцией confirm_test_extension_compiled, которая была добавлена скриптом ext_skel

Anton Dobkin
Author

Anton Dobkin

Comments