PHP开发第一个扩展

独立的 PHP 扩展可以独立于 PHP
源码之外进行分发。要创建一个这样的扩展,需要准备好两样东西:

首先声明:我们要构建的是扩展或者模块名为hello_module.该模块提供一个方法:hello_word.

  • 配置文件 (config.m4)
  • 你的模块源码

一、PHP环境的搭建

接下来我们来描述一下如果创建这些文件并组合起来。

1)一般使用源码包编译安装,而不是binary包安装。因为使用PHP的二进制分发包安装有些冒险,这些版本倾向于忽略./configure的两个重要选项,它们在开发过程中很便利:

准备好系统工具

想要扩展能够在系统上编译并成功运行,需要准备转以下工具:

  • GNU autoconf
  • GNU automake
  • GNU libtool
  • GNU m4

以上这些都可以从 获取。

注:以上这些都是类 Unix 环境下才能使用的工具。

第一个–enable-debug。这个选项将把附加的符号信息编译进PHP的执行文件,以便如果发生段错误,你能从中得到一个内核转储文件,使用gdb追踪并发现什么地方以及为什么会发生段错误。

改装一个已经存在的扩展

为了显示出创建一个独立的扩展是很容易的事情,我们先将一个已经内嵌到 PHP
的扩展改成独立扩展。安装 PHP 并且执行以下命令:

$ mkdir /tmp/newext
$ cd /tmp/newext

现在你已经有了一个空目录。我们将 mysql 扩展目录下的文件复制过来:

$ cp -rp php-4.0.X/ext/mysql/* .
# 注:看来这篇 README 真的需要更新一下了
# PHP7 中已经移除了 mysql 扩展部分

到这里扩展就完成了,执行:

$ phpize

现在你可以独立存放这个目录下的文件到任何地方,这个扩展可以完全独立存在了。

用户在编译时需要使用以下命令:

$ ./configure 
       [--with-php-config=/path/to/php-config] 
       [--with-mysql=MYSQL-DIR]
$ make install

这样 MySQL 模块就可以使用内嵌的 MySQL 客户端库或者已安装的位于 MySQL
目录中的 MySQL。

注:意思是说想要编写 PHP 扩展,你既需要已经安装了 PHP,也需要下载一份
PHP 源码。

2)另
一个选项依赖于你的PHP版本。在PHP
4.3中该选项名为–enable-experimental-zts,在PHP
5及以后的版本中为–enable-maintainer-zts。这个选项使PHP以为自己执行于多线程环境,并且使你能捕获通常的程序错误,然而它
们在非多线程环境中是无害的,却使你的扩展不可安全用于多线程环境。一旦你已经使用这些额外的选项编译了PHP并安装于你的开发服务器(或者工作站)中,你就可以把你的第一个扩展加入其中了。

定义一个新扩展

我们给示例扩展命名为 “foobar”。

新扩展包含两个资源文件:foo.c 和
bar.c(还有一些头文件,但这些不只重要)。

示例扩展不引用任何外部的库(这点很重要,因为这样用户就不需要特别指定一些编译选项了)。

LTLIBRARY_SOURCES
选项用于指定资源文件的名字,你可以有任意数量的资源文件。

注:上面说的是 Makefile.in 文件中的配置选项,可以参考
xdebug。

3)Zend
引擎提供了一个内存管理器,有在扩展中跟踪内存泄漏的能力并提供详尽的调试信息。跟踪在默认情况下是被禁用的,同时也是线程安全的。要打开的话,应将
–enable-debug 和 –enable-maintainer-zts 选项与其他常用选项一起传给
configure。要获得从源代码构建 PHP 的说明,请看位于 安装前需要考虑的事项
的说明。

修改 m4 后缀的配置文件

m4
配置文件可以指定一些额外的检查。对于一个独立扩展来说,你只需要做一些宏调用即可。

PHP_ARG_ENABLE(foobar,whether to enable foobar,
[  --enable-foobar            Enable foobar])

if test "$PHP_FOOBAR" != "no"; then
  PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)
fi

PHP_ARG_ENABLE 会自动设置好正确的变量以保证扩展能够被
PHP_NEW_EXTENSION 以共享模式启动。

PHP_NEW_EXTENSION
的第一个参数是扩展的名称,第二个参数是资源文件。第三个参数 $ext_shared
是由 PHP_ARG_ENABLE/WITHPHP_NEW_EXTENSION 设定的。

请始终使用 PHP_ARG_ENABLEPHP_ARG_WITH
进行设置。即使你不打算发布你的 PHP 模块,这些设置也可以保证让你的模块和
PHP 主模块的接口保持一体。

注:PHP_ARG_ENABLEPHP_ARG_WITH
应该是用于定义模块是动态扩展还是静态编译进 PHP 中,就跟编译 PHP 时使用的
--enable-xxx--with-xxx 一样。

典型的 configure
命令行可能看起来象这样:

创建资源文件

ext_skel 可以为你的 PHP
模块创建一些通用的代码,你也可以编写一些基本函数定义和 C
代码来处理函数的参数。具体信息可以查看
READNE.EXT_SKEL。

不要担心没有范例,PHP
中有很多模块供你参考,选择一个简单的点开始,添加你自己的代码。

注:ext_skel
可以生成好基本模块需要的资源文件和配置文件,不需要自己创建。

$ ./configure 
--prefix=/usr/local/php 
--enable-debug 
--enable-maintainer-zts  
--enable-cgi 
--enable-cli 
--with-mysql=/path/to/mysql 

修改自定义模块

将 config.m4 文件和资源文件放到同一个目录中,然后执行 phpize (PHP 4.0
以上的版本编译 PHP 的时候都安装了 phpize)。

如果你的 phpize 不在系统环境变量中,你需要指定绝对路径,例如:

$ /php/bin/phpize

这个命令会自动复制必需的构建文件到当前目录并根据 config.m4
创建配置文件。

通过以上的步骤,你已经有了一个独立的扩展了。

1)一般可以把php安装在/usr/local/php目录下。
2)php的二进制可执行文件都在/usr/local/php/bin目录,包括php自带工具phpize.

安装扩展

扩展可以通过以下命令编译安装:

$ ./configure 
            [--with-php-config=/path/to/php-config]
$ make install

phpize实际上是个shell脚本,可以用vi
phpize来查看其内容.
注意:使用phpize需要安装autoconf
宏。因为config.m4 文件使用 GNU autoconf
语法编写。简而言之,就是用强大的宏语言增强的 shell脚本。注释用字符串 dnl
分隔,字符串则放在左右方括号中间(例如,[ 和
])。字符串可按需要多次嵌套引用。完整的语法参考可参见位于
安装autoconf
宏最简单的方法:apt-get install autoconf

给模块添加共享支持

有时候独立扩展需要是共享的已供其他模块加载。接下来我会解释如何给已经创建好的
foo 模块添加共享支持。

  1. 在 config.m4 文件中,使用 PHP_ARG_WITH/PHP_ARG_ENABLE
    来设定扩展,这样就可以自动使用 --with-foo=shared[,..]
    --enable-foo=shared[,..] 这样的指令作为编译参数了。
  2. 在 config.m4 文件中,使用 PHP_NEW_EXTENSION(foo,.., $ext_shared)
    使扩展可以被构建。
  3. 添加以下代码到你的 C 语言资源文件中:

   #ifdef COMPILE_DL_FOO
   ZEND_GET_MODULE(foo)
   #endif

这一段讲的上面都提到过了,这里只是又强调了一下。

 

PECL 网站约定

如果你打算发布你的扩展到 PECL 的网站,需要考虑以下几点:

  1. 添加 LICENSE 或 COPYING 到 package.xml
  2. 需要在扩展头文件中定义好版本信息,这个宏会被 foo_module_entry
    调用来声明扩展版本:

   #define PHP_FOO_VERSION "1.2.3"

2、ext_skel脚本

PHP
扩展由几个文件组成,这些文件对所有扩展来说都是通用的。不同扩展之间,这些文件的很多细节是相似的,只是要费力去复制每个文件的内容。幸运的是,有脚本可以做所有的初始化工作,名为
ext_skel,自 PHP 4.0 起与其一起分发。

不带参数运行 ext_skel
在 PHP 5.3.2 中会产生以下输出:

./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 和 –no-help。除非已经熟悉扩展的结构,不要想去使用 –no-help;
指定此参数会造成 ext_skel
不会在生成的文件里省略很多有用的注释。

剩下的 –extname
会将扩展的名称传给 ext_skel。”name”
是一个全为小写字母的标识符,仅包含字母和下划线,在 PHP 发行包的 ext/
文件夹下是唯一的。

–proto选项允许开发人员指定一个头文件,由此创建一系列
PHP
函数,表面上看就是要开发基于一个函数库的扩展,但对大多数头现代的文件来说很少能起作用。如果用
zlib.h 头文件来做测试,就会导致在 ext_skel
的输出文件中存在大量的空的和无意义的原型文件。–xml 和 –full-xml
选项当前完全不起作用。–skel
选项可用于指定用一套修改过的框架文件来工作,这是本节范围之外的话题了

 

3、扩展组成文件

不管是通过手工,通过ext_skel
,还是通过另外的扩展生成器,所有的扩展都会有以下个文件:
1) 
config.m4:phpize

用来准备构建系统哪些扩展的配置文件configure
选项 ,是UNIX 构建系统配置。
对应的win系统是config.w32:
2)
php_hello_module.h:

包含引用的头文件当将扩展作为静态模块构建并放入PHP
二进制包时,构建系统要求用 php_澳门新葡亰赌995577, 加扩展的名称命名的
头文件包含一个对扩展模块结构的指针定义。就象其他头文件,此文件经常包含附加的宏、原型和全局量。当然你可以把头文件内容放在源文件hello_module.c顶部。分开只是让代码组织更清晰,而且是个很好的习惯。
3)
hello_module.c :
包含模块函数的源码文件

扩展应包含任意数量的头文件、源文件、单元测试和其他支持文件,此四个文件仅够组成最小的扩展。hello_module扩展的文件列表如下所示:

ext/hello_module/  
config.m4        
config.w32        
CREDITS        
EXPERIMENTAL       
php_hello_module.h        
hello_module.c        
tests/         
001.phpt 

 

4、与 UNIX 构建系统交互: config.m4

 

config.m4文件负责在配置时解析configure的命令行选项。这就是说它将检查所需的外部文件并且要做一些类似配置与安装的任务。config.m4
文件告诉 UNIX 构建系统哪些扩展 configure
选项是支持的,你需要哪些扩展库,以及哪些源文件要编译成它的一部分。对所有经常使用的
autoconf 宏,包括 PHP 特定的及 autoconf 内建的,
config.m4
文件举例

dnl $Id$  
dnl config.m4 for extension example  
PHP_ARG_WITH(example, for example support,  
[  --with-example[=FILE]       Include example support. File is the optional path to example-config])  
PHP_ARG_ENABLE(example-debug, whether to enable debugging support in example,  
[  --enable-example-debug        example: Enable debugging support in example], no, no)  
PHP_ARG_WITH(example-extra, for extra libraries for example,  
[  --with-example-extra=DIR      example: Location of extra libraries for example], no, no)  

dnl 检测扩展是否已启用  
if test "$PHP_EXAMPLE" != "no"; then  

dnl 检测 example-config。首先尝试所给出的路径,然后在 $PATH 中寻找  
AC_MSG_CHECKING([for example-config])  
EXAMPLE_CONFIG="example-config"  
if test "$PHP_EXAMPLE" != "yes"; then  
EXAMPLE_PATH=$PHP_EXAMPLE  
else  
EXAMPLE_PATH=`$php_shtool path $EXAMPLE_CONFIG`  
fi  

dnl 如果找到可用的 example-config,就使用它  
if test -f "$EXAMPLE_PATH" && test -x "$EXAMPLE_PATH" && $EXAMPLE_PATH --version > /dev/null 2>&1; then  
AC_MSG_RESULT([$EXAMPLE_PATH])  
EXAMPLE_LIB_NAME=`$EXAMPLE_PATH --libname`  
EXAMPLE_INCDIRS=`$EXAMPLE_PATH --incdirs`  
EXAMPLE_LIBS=`$EXAMPLE_PATH --libs`  

dnl 检测扩展库是否工作正常  
PHP_CHECK_LIBRARY($EXAMPLE_LIB_NAME, example_critical_function,  
[  
  dnl 添加所需的 include 目录  
  PHP_EVAL_INCLINE($EXAMPLE_INCDIRS)  
  dnl 添加所需的扩展库及扩展库所在目录  
  PHP_EVAL_LIBLINE($EXAMPLE_LIBS, EXAMPLE_SHARED_LIBADD)  
],[  
  dnl 跳出  
  AC_MSG_ERROR([example library not found. Check config.log for more information.])  
],[$EXAMPLE_LIBS]  
)  
else  
dnl 没有可用的 example-config,跳出  
AC_MSG_RESULT([not found])  
AC_MSG_ERROR([Please check your example installation.])  
fi  

dnl 检测是否启用调试  
if test "$PHP_EXAMPLE_DEBUG" != "no"; then  
dnl 是,则设置 C 语言宏指令  
AC_DEFINE(USE_EXAMPLE_DEBUG,1,[Include debugging support in example])  
fi  

dnl 检测额外的支持  
if test "$PHP_EXAMPLE_EXTRA" != "no"; then  
if test "$PHP_EXAMPLE_EXTRA" == "yes"; then  
  AC_MSG_ERROR([You must specify a path when using --with-example-extra])  
fi  

PHP_CHECK_LIBRARY(example-extra, example_critical_extra_function,  
[  
  dnl 添加所需路径  
  PHP_ADD_INCLUDE($PHP_EXAMPLE_EXTRA/include)  
  PHP_ADD_LIBRARY_WITH_PATH(example-extra, $PHP_EXAMPLE_EXTRA/lib, EXAMPLE_SHARED_LIBADD)  
  AC_DEFINE(HAVE_EXAMPLEEXTRALIB,1,[Whether example-extra support is present and requested])  
  EXAMPLE_SOURCES="$EXAMPLE_SOURCES example_extra.c"  
],[  
  AC_MSG_ERROR([example-extra lib not found. See config.log for more information.])  
],[-L$PHP_EXAMPLE_EXTRA/lib]  
)  
fi  

dnl 最后,将扩展及其所需文件等信息传给构建系统  
PHP_NEW_EXTENSION(example, example.c $EXAMPLE_SOURCES, $ext_shared)  
PHP_SUBST(EXAMPLE_SHARED_LIBADD)  
fi  

 

注意:凡是带有dnl前缀的都是注释,注释是不被解析的。

 

*4.1 PHP_ARG_:
赋予用户可选项

*在以上的
config.m4 例子中,两条注释后,最先见到的 3 行代码,使用了
PHP_ARG_WITH() 和 PHP_ARG_ENABLE()。这些给 configure
提供了可选项,和在运行 ./configure –help
时显示的帮助文本。就象名称所暗示的,其两者的不同点在于是创建 –with-

选项还是 –enable-*
选项。每个扩展应提供至少一个以上的选项以及扩展名称,以便用户可选择是否将扩展构建至
PHP 中。按惯例,PHP_ARG_WITH()
用于取得参数的选项,例如扩展所需库或程序的位置;而 PHP_ARG_ENABLE()
用于代表简单标志的选项。

不管你使用哪一个指令,你都应该注释掉另外一个。也就是说,如果你使用了–enable-my_module,那就应该去掉–with-my_module。反之亦然。
configue使用例子:./configure   –enable-hello_module
则将

 

发表评论

电子邮件地址不会被公开。 必填项已用*标注

相关文章

网站地图xml地图