PHP Extension Development Introductory Tutorial _php instance

PHP Extension Development

I'm going to summarize my learning and understanding of PHP Extension Development in this series, trying to simply and clearly describe the basics of developing a PHP extension in a Linux system. The level is low, inevitably has the mistake, hoped to point out.

Preparatory work

Start by getting a copy of the PHP source code (you can check it out on GitHub, or download the latest stable version on the official website) and compile it. To speed up the compilation, we recommend disabling all additional extensions (using the--disable-all option), but it's a good idea to turn on debug (using the--enable-debug option) and thread safety (using--ENABLE-MAINTAINER-ZTS). However, to turn off debug when publishing the extension, choose whether to turn on thread safety as appropriate:
Copy the Code code as follows:
$./buildconf--force
$./configure--disable-all--enable-debug--enable-maintainer-zts
$ make

Note that we did not specify the--prefix option (and also no make install), because this is not required. Note that if you look at the output information, you may need to install some dependent packages to successfully compile PHP.

Compiled PHP executable program in the source code of the SAPI directory, corresponding to different host environments have different subdirectories, we will use the CLI (Command line interface) environment, we can build an alias for easy reference:
Copy the Code code as follows:
$ alias php-dev=/usr/local/src/php-5.6.5/sapi/cli/php

There are a few command-line options that are useful:
Copy the Code code as follows:
PHP-DEV-H # Printing Help information
PHP-DEV-V # Print version information
Php-dev--ini # Print configuration information
PHP-DEV-M # Print Loaded module information
Php-dev-i # Phpinfo
Php-dev-r　　　　　　# 执行code里的代码


扩展骨架

PHP的所有官方扩展都在源码的ext目录下，我们自己写的扩展也可以放在该目录下。注意，该目录下有个名为ext_skel的shell脚本，它是用来生成PHP扩展骨架的，使用该脚本，可以帮我们快速创建PHP扩展：
复制代码 代码如下:
$ ./ext_skel --extname=myext

上面的命令帮我们创建了一个名为myext的扩展，源码在myext目录下。不带任何参数的执行该脚本可以打印帮助信息，这样你可以查看到该脚本提供的更多选项。

接下来让我们完成我们的扩展。进入myext目录，编辑config.m4配置文件，找到PHP_ARG_ENABLE宏函数，去掉前面的dnl注释（共三行）。退回到源码根目录，重新执行buildconf、configure和make命令：
复制代码 代码如下:
$ ./buildconf --force
$ ./configure --help | grep myext
--enable-myext Enable myext support
$ ./configure --disable-all --enable-myext --enable-debug --enable-maintainer-zts
$ make


注意，我们用./configure --help | grep myext打印了我们扩展的加载情况，如果看不到下面的输出，则说明我们的扩展没有配置成功，回头检查下config.m4文件。

这次编译应该非常快，因为大部分代码都已经编译过了。PHP还有另外一种编译扩展的方法（使用动态连接的方式，将扩展编译为.so的文件），不过我们推荐在开发扩展的时候使用静态编译，因为这样省去了在配置文件中加载扩展的步骤。

一切顺利的话，我们的第一个扩展就已经可以执行了：
复制代码 代码如下:
$ php-dev -m | grep myext
myext
$ php-dev -r 'echo confirm_myext_compiled("myext") . "\n";'
Congratulations! You have successfully modified ext/myext/config.m4. Module myext is now compiled into PHP.

第一个命令显示了我们的扩展已经被加载。第二个命令执行了ext_skel扩展骨架自动为我们创建的函数。当然，这个函数毫无意义，不过我们可以很容易的把这个函数改编成hello world。

手动创建扩展

大部分教程都是以ext_skel扩展骨架为原型讲述扩展开发的，这种做法当然很方便快捷。但是我个人更喜欢纯手工开发扩展的方式，因为这样更容易理解其中的每一个细节。

手动创建扩展，先进入ext目录，创建我们的扩展目录myext2。有几个文件是必须的：config.m4，myext2.c和php_myext2.h。

首先，我们来编写配置文件config.m4：
复制代码 代码如下:
PHP_ARG_ENABLE(myext2, whether to enable myext2 support,
[ --enable-myext2 Enable myext2 support])

if test "PHP_MYEXT2" != "no"; then
PHP_NEW_EXTENSION(myext2, myext2.c, $ext_shared)
fi

config.m4其实是autoconf程序使用的配置文件，autoconf是autotools工具箱里重要的组成。完整介绍autoconf的用法是需要很长时间的，好在我们这里的用法非常简单。

PHP_ARG_ENABLE是PHP为autoconf定义的宏函数，myext2是它的第一个参数，指出了扩展的名字；后面两个参数只是在make和configure执行时用来显示的，所以我们可以随便写。[ ]在autoconf语法中的作用类似于双引号，用来包裹字符串（注意第二个参数中包含了空格，但是可以不用方括号起来）。还有第四个参数用来指明扩展默认是开启还是关闭（yes或no），默认是no。

下面三行其实就是shell语法，判断我们是否开启了PHP_MYEXT2扩展模块。如果开启了该扩展模块（--enable-myext2），则$PHP_MYEXT2变量的值不为no，因此执行PHP_NEW_EXTENSION宏。这个宏函数也是PHP为autoconf定义的扩展语法，第一个参数同样是扩展名称；第二个参数是扩展要编译的C文件，如果有多个，依次写下去就可以了（空格分隔）；第三个参数固定是$ext_shared。

接下来编写php_myext2.h头文件，该文件的命名是PHP扩展的规范 — php_扩展名.h：
复制代码 代码如下:
#ifndef PHP_MYEXT2_H
#define PHP_MYEXT2_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 */


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

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

最后来看下myext2.c文件的实现：
复制代码 代码如下:
#include "php.h"
#include "php_myext2.h"

/* {{{ 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扩展。

最后，编译运行我们的扩展：
复制代码 代码如下:
$ ./buildconf --force
$ ./configure --help | grep myext2
--enable-myext2 Enable myext2 support
$ ./configure --disable-all --enable-myext2 --enable-debug --enable-maintainer-zts
$ make

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


