PHP extension development
I am going to summarize my learning and insights about PHP extension development in this series of blog posts, trying to simply and clearly describe the most basic knowledge that should be possessed to develop a PHP extension under Linux system. My level is low, so there are bound to be mistakes. Please point them out.
Preparation
First, you need to obtain a copy of the PHP source code (you can check it out from Github, or download the latest stable version from the official website), and then compile it. To speed up compilation, we recommend disabling all extra extensions (using the --disable-all option), but it is better to turn on debugging (using the --enable-debug option) and thread safety (using --enable-maintainer-zts), But you need to turn off debugging when publishing the extension, and choose whether to turn on thread safety according to the situation:
The compiled PHP executable program is in the sapi directory of the source code. There are different subdirectories corresponding to different host environments. We will mainly use the cli (command line interface) environment in the future. You can create an alias for easy reference:
There are some command line options that are useful:
#Execute the code in code
Extended skeleton
All official extensions of PHP are in the ext directory of the source code. Extensions we write ourselves can also be placed in this directory. Note that there is a shell script named ext_skel in this directory, which is used to generate a PHP extension skeleton. Using this script can help us quickly create a PHP extension:
Next let’s finalize our extension. Enter the myext directory, edit the config.m4 configuration file, find the PHP_ARG_ENABLE macro function, and remove the previous dnl comment (three lines in total). Return to the source code root directory and re-execute the buildconf, configure and make commands:
Note that we used ./configure --help | grep myext to print the loading status of our extension. If you cannot see the following output, it means that our extension was not configured successfully. Go back and check the config.m4 file.
This compilation should be very fast because most of the code has already been compiled. PHP has another way to compile extensions (using dynamic linking to compile the extension into a .so file), but we recommend using static compilation when developing extensions, because this eliminates the need to load the extension in the configuration file. steps.
If all goes well, our first extension will be ready to execute:
Manually create extensions
Most tutorials use the ext_skel extension skeleton as a prototype to describe extension development. This approach is of course very convenient and fast. But I personally prefer to develop extensions purely by hand, because it is easier to understand every detail.
To create an extension manually, first enter the ext directory and create our extension directory myext2. Several files are required: config.m4, myext2.c and php_myext2.h.
First, let’s write the configuration file config.m4:
if test "PHP_MYEXT2" != "no"; then
PHP_NEW_EXTENSION(myext2, myext2.c, $ext_shared)
fi
PHP_ARG_ENABLE is a macro function defined by PHP for autoconf. Myext2 is its first parameter, indicating the name of the extension; the latter two parameters are only used to display when make and configure are executed, so we can write whatever we want. [ ] functions like double quotes in autoconf syntax, used to wrap strings (note that the second parameter contains spaces, but it does not need to be enclosed in square brackets). There is also a fourth parameter used to indicate whether the extension is on or off by default (yes or no). The default is no.
The following three lines are actually shell syntax to determine whether we have enabled the PHP_MYEXT2 extension module. If the extension module is enabled (--enable-myext2), the value of the $PHP_MYEXT2 variable is not no, so the PHP_NEW_EXTENSION macro is executed. This macro function is also the extension syntax defined by PHP for autoconf. The first parameter is also the extension name; the second parameter is the C file to be compiled by the extension. If there are multiple, just write them down in sequence (separated by spaces); The three parameters are fixed to $ext_shared.
Next, write the php_myext2.h header file. The naming of this file is the specification of the PHP extension - php_extension.h:
extern zend_module_entry myext2_module_entry;
#define phpext_myext2_ptr &myext2_module_entry
#define PHP_MYEXT2_VERSION "0.1.0"
/* prototypes */
PHP_FUNCTION(hello);
#endif /* PHP_MYEXT2_H */
The main code here is to define a macro named phpext_myext2_ptr. The bottom layer of PHP refers to our extension through this macro. It can be seen that the naming of this macro is also standardized - phpext_extension_ptr. Myext2_module_entry is a structure that we will define in the .c file later, and its naming is also standardized - extension _module_entry.
In addition, we also defined a macro that identifies our extended version number and a function prototype (through the PHP_FUNCTION macro, the parameter of the PHP_FUNCTION macro function is the externally usable function name). We will implement this function later.
Finally, let’s look at the implementation of the myext2.c file:
/* {{{ myext2_functions[]
*
* Every user visible function must have an entry in myext2_functions[].
*/
static const zend_function_entry myext2_functions[] = {
PHP_FE(hello, NULL)
PHP_FE_END
};
/* }}} */
/* {{{ myext2_module_entry
*/
zend_module_entry myext2_module_entry = {
STANDARD_MODULE_HEADER,
"myext2", /* module name */
myext2_functions, /* module functions */
NULL, /* module initialize */
NULL, /* module shutdown */
NULL, /* request initialize */
NULL, /* request shutdown */
NULL, /* phpinfo */
PHP_MYEXT2_VERSION, /* module version */
STANDARD_MODULE_PROPERTIES
};
/* }}} */
#ifdef COMPILE_DL_MYEXT2
ZEND_GET_MODULE(myext2)
#endif
/* {{{ proto void hello()
Print "hello world!" */
PHP_FUNCTION(hello)
{
php_printf("hello world!n");
}
/* }}} */
对比下扩展骨架创建的.c文件就会发现,我们的.c文件非常的简单,其实这些对一个最基本的扩展来说就已经足够了。
上面的代码是简单而清晰的,大部分注释已经很具说明性了。我们再简要概括下:
1.开头包含我们要用到的头文件。php.h是必须的,它已经帮我们包含了我们会用到的绝大多数的标准库文件,比如stdio.h,stdlib.h等等。
2.myext2_functions定义了由我们要暴露出去的函数构成的结构体数组,每一个元素通过PHP_FE宏来指定。PHP_FE宏有两个参数,第一个是外部可使用的函数名,第二个是参数信息(这里我们简单使用了NULL),最后一个元素必须是PHP_FE_END。注意它的注释,再次强调,每一个要暴露给外部使用的函数,都必须在该结构体数组中有定义。
3.myext2_module_entry定义了我们的模块信息,它是一个结构体,大部分属性都已经通过注释给出了说明。注意中间的五个函数指针,我们都简单的置为了NULL,在后续的博文中会讲述它们的用法。
4.ZEND_GET_MODULE(myext2)宏函数是被ifdef宏包含的,所以说它是否调用是视情况而定的。至于什么情况下会被调用,什么情况下不会被调用,在后续的博文中会讲述。
5.最后几行代码我们实现了hello函数,它很简单,调用php_printf输出hello world!跟一个换行符,php_printf的用法和printf完全一样。
6.注释里的 {{{ 和 }}} 是为了方便vim等编辑器折叠而使用的,我们推荐你也这样来写注释。
这里面涉及了一些宏,比如PHP_FE,PHP_FE_END,PHP_FUNCTION等等,完整介绍这些宏要到后续的博文中才可以,眼下最简单的办法就是记住这些宏。
注意到我们每一个文件的命名,变量的命名,空格和缩进,以及注释等都是非常规范的,遵循这些规范,可以使我们编写的代码和PHP本身的代码更加契合,我们也推荐你使用这样的规范来开发PHP扩展。
最后,编译运行我们的扩展:
$ php-dev -m | grep myext2
myext2
$ php-dev -r 'hello();'
hello world!