PHP extension development (1): Getting started, php extension

PHP extension development (1): Getting started, php extensions

There are many articles and blogs about PHP extension development, the more classic ones are:

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, 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:

$ ./buildconf --<span>force
$ .</span>/configure --disable-all --enable-debug --enable-maintainer-<span>zts
$ </span><span>make</span>

Copy after login

Note that we did not specify the --prefix option (nor make install) as this is not required. Pay attention to the output information. You may need to install some dependency packages to successfully compile PHP.

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:

$ alias php-dev=/usr/local/src/php-<span>5.6</span>.<span>5</span>/sapi/cli/php

Copy after login

There are some command line options that are useful:

php-dev -<span>h　　　　　　　　　　# 打印帮助信息
php</span>-dev -<span>v　　　　　　　　　　# 打印版本信息
php</span>-dev --<span>ini　　　　　　　　# 打印配置信息        
php</span>-dev -<span>m　　　　　　　　　　# 打印加载的模块信息
php</span>-dev -<span>i　　　　　　　　　　# phpinfo
php</span>-dev -r <code>　　　　　　# 执行code里的代码

Copy after login

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:

$ ./ext_skel --extname=myext

Copy after login

The above command helps us create an extension named myext, and the source code is in the myext directory. Executing the script without any parameters prints help information so you can see more options provided by the script.

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:

$ ./buildconf --<span>force
$ .</span>/configure --help | <span>grep</span><span> myext
    </span>--enable-<span>myext           Enable myext support
$ .</span>/configure --disable-all --enable-myext --enable-debug --enable-maintainer-<span>zts
$ </span><span>make</span>

Copy after login

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 since 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:

$ php-dev -m | <span>grep</span><span> myext
myext
$ php</span>-dev -r <span>'</span><span>echo confirm_myext_compiled("myext") . "\n";</span><span>'</span><span>
Congratulations</span>! You have successfully modified ext/myext/config.m4. Module myext is now compiled into PHP.

Copy after login

The first command shows that our extension has been loaded. The second command executes the function that the ext_skel extension skeleton automatically created for us. Of course, this function is meaningless, but we can easily adapt this function to hello world.

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:

PHP_ARG_ENABLE(myext2, whether to enable myext2 support,
<span>[</span><span>  --enable-myext2           Enable myext2 support</span><span>]</span><span>)
</span>
if test "PHP_MYEXT2" != "no"<span>;</span><span> then</span>
   PHP_NEW_EXTENSION(myext2, myext2.c,<span> $ext_shared)
</span>fi

Copy after login

Config.m4 is actually the configuration file used by the autoconf program. Autoconf is an important component in the autotools toolbox. It would take a long time to fully introduce the usage of autoconf. Fortunately, the usage here is very simple.

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:

<span> 1</span> <span>#ifndef PHP_MYEXT2_H
</span><span> 2</span> <span>#define</span> PHP_MYEXT2_H
<span> 3</span> 
<span> 4</span> <span>extern</span><span> zend_module_entry myext2_module_entry;
</span><span> 5</span> <span>#define</span> phpext_myext2_ptr &myext2_module_entry
<span> 6</span> 
<span> 7</span> <span>#define</span> PHP_MYEXT2_VERSION "0.1.0"
<span> 8</span> 
<span> 9</span> <span>/*</span><span> prototypes </span><span>*/</span>
<span>10</span> <span>PHP_FUNCTION(hello);
</span><span>11</span> 
<span>12</span> <span>#endif</span>  /* PHP_MYEXT2_H */

Copy after login

这里主要的代码是定义了名为phpext_myext2_ptr的宏，PHP底层通过该宏来引用我们的扩展。可以看出，该宏的命名同样是有规范的 — phpext_扩展名_ptr。而myext2_module_entry是我们稍后要在.c文件里定义的结构体，它的命名也是规范的 — 扩展名_module_entry。

此外我们还定义了一个标识我们扩展版本号的宏和一个函数原型（通过PHP_FUNCTION宏，PHP_FUNCTION宏函数的参数是外部可使用的函数名），稍后我们会来实现这个函数。

最后来看下myext2.c文件的实现：

<span> 1</span> #include <span>"</span><span>php.h</span><span>"</span>
<span> 2</span> #include <span>"</span><span>php_myext2.h</span><span>"</span>
<span> 3</span> 
<span> 4</span> <span>/*</span><span> {{{ myext2_functions[]
</span><span> 5</span> <span> *
</span><span> 6</span> <span> * Every user visible function must have an entry in myext2_functions[].
</span><span> 7</span>  <span>*/</span>
<span> 8</span> <span>static</span> <span>const</span> zend_function_entry myext2_functions[] =<span> {
</span><span> 9</span> <span>    PHP_FE(hello,       NULL)
</span><span>10</span> <span>    PHP_FE_END
</span><span>11</span> <span>};
</span><span>12</span> <span>/*</span><span> }}} </span><span>*/</span>
<span>13</span> 
<span>14</span> <span>/*</span><span> {{{ myext2_module_entry
</span><span>15</span>  <span>*/</span>
<span>16</span> zend_module_entry myext2_module_entry =<span> {
</span><span>17</span> <span>    STANDARD_MODULE_HEADER,
</span><span>18</span>     <span>"</span><span>myext2</span><span>"</span>,               <span>/*</span><span> module name </span><span>*/</span>
<span>19</span>     myext2_functions,       <span>/*</span><span> module functions </span><span>*/</span>
<span>20</span>     NULL,                   <span>/*</span><span> module initialize </span><span>*/</span>
<span>21</span>     NULL,                   <span>/*</span><span> module shutdown </span><span>*/</span>
<span>22</span>     NULL,                   <span>/*</span><span> request initialize </span><span>*/</span>
<span>23</span>     NULL,                   <span>/*</span><span> request shutdown </span><span>*/</span>
<span>24</span>     NULL,                   <span>/*</span><span> phpinfo </span><span>*/</span>
<span>25</span>     PHP_MYEXT2_VERSION,     <span>/*</span><span> module version </span><span>*/</span>
<span>26</span> <span>    STANDARD_MODULE_PROPERTIES
</span><span>27</span> <span>};
</span><span>28</span> <span>/*</span><span> }}} </span><span>*/</span>
<span>29</span> 
<span>30</span> <span>#ifdef COMPILE_DL_MYEXT2
</span><span>31</span> <span>ZEND_GET_MODULE(myext2)
</span><span>32</span> <span>#endif</span>
<span>33</span> 
<span>34</span> <span>/*</span><span> {{{ proto void hello()
</span><span>35</span> <span>   Print "hello world!" </span><span>*/</span>
<span>36</span> <span>PHP_FUNCTION(hello)
</span><span>37</span> <span>{
</span><span>38</span>     php_printf(<span>"</span><span>hello world!\n</span><span>"</span><span>);
</span><span>39</span> <span>}
</span><span>40</span> <span>/*</span><span> }}} </span><span>*/</span>

Copy after login

对比下扩展骨架创建的.c文件就会发现，我们的.c文件非常的简单，其实这些对一个最基本的扩展来说就已经足够了。

上面的代码是简单而清晰的，大部分注释已经很具说明性了。我们再简要概括下：

这里面涉及了一些宏，比如PHP_FE，PHP_FE_END，PHP_FUNCTION等等，完整介绍这些宏要到后续的博文中才可以，眼下最简单的办法就是记住这些宏。

注意到我们每一个文件的命名，变量的命名，空格和缩进，以及注释等都是非常规范的，遵循这些规范，可以使我们编写的代码和PHP本身的代码更加契合，我们也推荐你使用这样的规范来开发PHP扩展。

最后，编译运行我们的扩展：

$ ./buildconf --<span>force
$ .</span>/configure --help | <span>grep</span><span> myext2
  </span>--enable-<span>myext2           Enable myext2 support
$ .</span>/configure --disable-all --enable-myext2 --enable-debug --enable-maintainer-<span>zts
$ </span><span>make</span><span>

$ php</span>-dev -m | <span>grep</span><span> myext2
myext2
$ php</span>-dev -r <span>'</span><span>hello();</span><span>'</span><span>
hello world</span>!

Copy after login