如何编写 php 扩展 翻译： taft@wjl.cn ver 0.1 最后修改日期 2006/1/19 wjl studio @ wjl.cn 2006 目 录 简 介 .... 3 快速开始 .... 3 内存管理 .... 7 从 php 函数中返回值 .... 7 完成 self_concat() 8 实例小结 .... 9 包裹第三方的扩展 .... 9 编写利
如何编写php扩展
翻译：taft@wjl.cn
ver 0.1
最后修改日期 2006/1/19
wjl studio @ wjl.cn 2006
目 录
简 介.... 3
快速开始.... 3
内存管理.... 7
从php函数中返回值.... 7
完成self_concat()8
实例小结.... 9
包裹第三方的扩展.... 9
编写利用资源的第一个php函数.... 12
全局变量.... 16
添加自定义ini指令.... 17
线程安全资源管理宏.... 18
总 结.... 19
词汇表.... 19
简 介
php取得成功的一个主要原因之一是她拥有大量的可用扩展。web开发者无论有何种需求，这种需求最有可能在php发行包里找到。php发行包包括支持各种数据库，图形文件格式，压缩，xml技术扩展在内的许多扩展。
扩展api的引入使php3取得了巨大的进展，扩展api机制使php开发社区很容易的开发出几十种扩展。现在，两个版本过去了，api仍然和php3时的非常相似。扩展主要的思想是：尽可能的从扩展编写者那里隐藏php的内部机制和脚本引擎本身，仅仅需要开发者熟悉api。
有两个理由需要自己编写php扩展。第一个理由是：php需要支持一项她还未支持的技术。这通常包括包裹一些现成的c函数库，以便提供php接口。例如，如果一个叫foobase的数据库已推出市场，你需要建立一个php扩展帮助你从php里调用foobase的c函数库。这个工作可能仅由一个人完成，然后被整个php社区共享（如果你愿意的话）。第二个不是很普遍的理由是：你需要从性能或功能的原因考虑来编写一些商业逻辑。
如果以上的两个理由都和你没什么关系，同时你感觉自己没有冒险精神，那么你可以跳过本章。
本章教你如何编写相对简单的php扩展，使用一部分扩展api函数。对于大多数打算开发自定义php扩展开发者而言，它含概了足够的资料。学习一门编程课程的最好方法之一就是动手做一些极其简单的例子，这些例子正是本章的线索。一旦你明白了基础的东西，你就可以在互联网上通过阅读文挡、原代码或参加邮件列表新闻组讨论来丰富自己。因此，本章集中在让你如何开始的话题。在unix下一个叫ext_skel的脚本被用于建立扩展的骨架，骨架信息从一个描述扩展接口的定义文件中取得。因此你需要利用unix来建立一个骨架。windows开发者可以使用windows ext_skel_win32.php代替ext_skel。
然而，本章关于用你开发的扩展编译php的指导仅涉及unix编译系统。本章中所有的对api的解释与unix和windows下开发的扩展都有联系。
当你阅读完这章，你能学会如何
? 建立一个简单的商业逻辑扩展。
? .建议个c函数库的包裹扩展，尤其是有些标准c文件操作函数比如fopen()
快速开始
本节没有介绍关于脚本引擎基本构造的一些知识，而是直接进入扩展的编码讲解中，因此不要担心你无法立刻获得对扩展整体把握的感觉。假设你正在开发一个网站，需要一个把字符串重复n次的函数。下面是用php写的例子：
function self_concat($string, $n)
{
$result = ;
for ($i = 0; $i
$result .= $string;
}
return $result;
}
self_concat(one, 3) returns oneoneone.
self_concat(one, 1) returns one.
假设由于一些奇怪的原因，你需要时常调用这个函数，而且还要传给函数很长的字符串和大值n。这意味着在脚本里有相当巨大的字符串连接量和内存重新分配过程，以至显著地降低脚本执行速度。如果有一个函数能够更快地分配大量且足够的内存来存放结果字符串，然后把$string重复n次，就不需要在每次循环迭代中分配内存。
为扩展建立函数的第一步是写一个函数定义文件，该函数定义文件定义了扩展对外提供的函数原形。该例中，定义函数只有一行函数原形self_concat() :
string self_concat(string str, int n)
函数定义文件的一般格式是一个函数一行。你可以定义可选参数和使用大量的php类型，包括: bool, float, int, array等。
保存为myfunctions.def文件至php原代码目录树下。
该是通过扩展骨架(skeleton)构造器运行函数定义文件的时机了。该构造器脚本叫ext_skel，放在php原代码目录树的ext/目录下（php原码主目录下的readme.ext_skel提供了更多的信息）。假设你把函数定义保存在一个叫做myfunctions.def的文件里，而且你希望把扩展取名为myfunctions，运行下面的命令来建立扩展骨架
./ext_skel --extname=myfunctions --proto=myfunctions.def
这个命令在ext/目录下建立了一个myfunctions/目录。你要做的第一件事情也许就是编译该骨架，以便编写和测试实际的c代码。编译扩展有两种方法：
?  作为一个可装载模块或者dso（动态共享对象）
? 静态编译到php
因为第二种方法比较容易上手，所以本章采用静态编译。如果你对编译可装载扩展模块感兴趣，可以阅读php原代码根目录下的readme.self-contained_extensions文件。为了使扩展能够被编译，需要修改扩展目录ext/myfunctions/下的config.m4文件。扩展没有包裹任何外部的c库，你需要添加支持--enable-myfunctions配置开关到php编译系统里（–with-extension 开关用于那些需要用户指定相关c库路径的扩展）。可以去掉自动生成的下面两行的注释来开启这个配置。
php_arg_enable(myfunctions, whether to enable myfunctions support,
[ --enable-myfunctions                include myfunctions support])
现在剩下的事情就是在php原代码树根目录下运行./buildconf，该命令会生成一个新的配置脚本。通过查看./configure --help输出信息，可以检查新的配置选项是否被包含到配置文件中。现在，打开你喜好的配置选项开关和--enable-myfunctions重新配置一下php。最后的但不是最次要的是，用make来重新编译php。
       ext_skel应该把两个php函数添加到你的扩展骨架了：打算实现的self_concat()函数和用于检测myfunctions 是否编译到php的confirm_myfunctions_compiled()函数。完成php的扩展开发后，可以把后者去掉。
运行这个脚本会出现类似下面的输出：
congratulations! you have successfully modified ext/myfunctions
config.m4. module myfunctions is now compiled into php.
另外，ext_skel脚本生成一个叫myfunctions.php的脚本，你也可以利用它来验证扩展是否被成功地编译到php。它会列出该扩展所支持的所有函数。
       现在你学会如何编译扩展了，该是真正地研究self_concat()函数的时候了。
              下面就是ext_skel脚本生成的骨架结构：
/* {{{ proto string self_concat(string str, int n)
*/
php_function(self_concat)
}
char *str = null;
int argc = zend_num_args();
int str_len;
long n;
if (zend_parse_parameters(argc tsrmls_cc, sl, &str, &str_len, &n) == failure)
return;
php_error(e_warning, self_concat: not yet implemented);
}
/* }}} */
自动生成的php函数周围包含了一些注释，这些注释用于自动生成代码文档和vi、emacs等编辑器的代码折叠。函数自身的定义使用了宏php_function()，该宏可以生成一个适合于zend引擎的函数原型。逻辑本身分成语义各部分，取得调用函数的参数和逻辑本身。
       为了获得函数传递的参数，可以使用zend_parse_parameters()api函数。下面是该函数的原型：
zend_parse_parameters(int num_args tsrmls_dc, char *type_spec, …);
第一个参数是传递给函数的参数个数。通常的做法是传给它zend_num_args()。这是一个表示传递给函数参数总个数的宏。第二个参数是为了线程安全，总是传递tsrmls_cc宏，后面会讲到。第三个参数是一个字符串，指定了函数期望的参数类型，后面紧跟着需要随参数值更新的变量列表。因为php采用松散的变量定义和动态的类型判断，这样做就使得把不同类型的参数转化为期望的类型成为可能。例如，如果用户传递一个整数变量，可函数需要一个浮点数，那么zend_parse_parameters()就会自动地把整数转换为相应的浮点数。如果实际值无法转换成期望类型（比如整形到数组形），会触发一个警告。
下表列出了可能指定的类型。我们从完整性考虑也列出了一些没有讨论到的类型。
类型指定符
对应的c类型
描述
l
long
符号整数
d
double
浮点数
s
char *, int
二进制字符串，长度
b
zend_bool
逻辑型（1或0）
r
zval *
资源（文件指针，数据库连接等）
a
zval *
联合数组
o
zval *
任何类型的对象
o
zval *
指定类型的对象。需要提供目标对象的类类型
z
zval *
无任何操作的zval
为了容易地理解最后几个选项的含义，你需要知道zval是zend引擎的值容器[1]。无论这个变量是布尔型，字符串型或者其他任何类型，其信息总会包含在一个zval联合体中。本章中我们不直接存取zval，而是通过一些附加的宏来操作。下面的是或多或少在c中的zval, 以便我们能更好地理解接下来的代码。
typedef union _zval {
long lval;
double dval;
struct {
char *val;
int len;
} str;
hashtable *ht;
zend_object_value obj;
} zval;
在我们的例子中，我们用基本类型调用zend_parse_parameters()，以本地c类型的方式取得函数参数的值，而不是用zval容器。
为了让zend_parse_parameters()能够改变传递给它的参数的值，并返回这个改变值，需要传递一个引用。仔细查看一下self_concat()：
if (zend_parse_parameters(argc tsrmls_cc, sl, &str, &str_len, &n) == failure)
return;
注意到自动生成的代码会检测函数的返回值failuer(成功即success)来判断是否成功。如果没有成功则立即返回，并且由zend_parse_parameters()负责触发警告信息。因为函数打算接收一个字符串l和一个整数n，所以指定 ”sl” 作为其类型指示符。s需要两个参数，所以我们传递参考char * 和 int (str 和 str_len)给zend_parse_parameters()函数。无论什么时候，记得总是在代码中使用字符串长度str_len来确保函数工作在二进制安全的环境中。不要使用strlen()和strcpy()，除非你不介意函数在二进制字符串下不能工作。二进制字符串是包含有nulls的字符串。二进制格式包括图象文件，压缩文件，可执行文件和更多的其他文件。”l” 只需要一个参数，所以我们传递给它n的引用。尽管为了清晰起见，骨架脚本生成的c变量名与在函数原型定义文件中的参数名一样；这样做不是必须的，尽管在实践中鼓励这样做。
回到转换规则中来。下面三个对self_concat()函数的调用使str, str_len和n得到同样的值：
self_concat(321, 5);
self_concat(321, 5);
self_concat(321, 5);
str points to the string 321, str_len equals 3, and n equals 5.
str 指向字符串321，str_len等于3，n等于5。
在我们编写代码来实现连接字符串返回给php的函数前，还得谈谈两个重要的话题：内存管理、从php内部返回函数值所使用的api。
内存管理
用于从堆中分配内存的php api几乎和标准c api一样。在编写扩展的时候，使用下面与c对应（因此不必再解释）的api函数：
emalloc(size_t size);
efree(void *ptr);
ecalloc(size_t nmemb, size_t size);
erealloc(void *ptr, size_t size);
estrdup(const char *s);
estrndup(const char *s, unsigned int length);
在这一点上，任何一位有经验的c程序员应该象这样思考一下：“什么？标准c没有strndup()？”是的，这是正确的，因为gnu扩展通常在linux下可用。estrndup()只是php下的一个特殊函数。它的行为与estrdup()相似，但是可以指定字符串重复的次数（不需要结束空字符），同时是二进制安全的。这是推荐使用estrndup()而不是estrdup()的原因。
在几乎所有的情况下，你应该使用这些内存分配函数。有一些情况，即扩展需要分配在请求中永久存在的内存，从而不得不使用malloc()，但是除非你知道你在做什么，你应该始终使用以上的函数。如果没有使用这些内存函数，而相反使用标准c函数分配的内存返回给脚本引擎，那么php会崩溃。
这些函数的优点是：任何分配的内存在偶然情况下如果没有被释放，则会在页面请求的最后被释放。因此，真正的内存泄漏不会产生。然而，不要依赖这一机制，从调试和性能两个原因来考虑，应当确保释放应该释放的内存。剩下的优点是在多线程环境下性能的提高，调试模式下检测内存错误等。
       还有一个重要的原因，你不需要检查这些内存分配函数的返回值是否为null。当内存分配失败，它们会发出e_error错误，从而决不会返回到扩展。
从php函数中返回值
扩展api包含丰富的用于从函数中返回值的宏。这些宏有两种主要风格：第一种是retval_type()形式，它设置了返回值但c代码继续执行。这通常使用在把控制交给脚本引擎前还希望做的一些清理工作的时候使用，然后再使用c的返回声明 ”return” 返回到php；后一个宏更加普遍，其形式是return_type()，他设置了返回类型，同时返回控制到php。下表解释了大多数存在的宏。
设置返回值并且结束函数
设置返回值
宏返回类型和参数
return_long(l)
retval_long(l)
整数
return_bool(b)
retval_bool(b)
布尔数(1或0)
return_null()
retval_null()
null
return_double(d)
retval_double(d)
浮点数
return_string(s, dup)
retval_string(s, dup)
字符串。如果dup为1，引擎会调用estrdup()重复s，使用拷贝。如果dup为0，就使用s
return_stringl(s, l, dup)
retval_stringl(s, l, dup)
长度为l的字符串值。与上一个宏一样，但因为s的长度被指定，所以速度更快。
return_true
retval_true
返回布尔值true。注意到这个宏没有括号。
return_false
retval_false
返回布尔值false。注意到这个宏没有括号。
return_resource(r)
retval_resource(r)
资源句柄。
完成self_concat()
现在你已经学会了如何分配内存和从php扩展函数里返回函数值，那么我们就能够完成self_concat()的编码：
/* {{{ proto string self_concat(string str, int n)
*/
php_function(self_concat)
}
char *str = null;
int argc = zend_num_args();
int str_len;
long n;
char *result; /* points to resulting string */
char *ptr; /* points at the next location we want to copy to */
int result_length; /* length of resulting string */
if (zend_parse_parameters(argc tsrmls_cc, sl, &str, &str_len, &n) == failure)
return;
/* calculate length of result */
result_length = (str_len * n);
/* allocate memory for result */
result = (char *) emalloc(result_length + 1);
/* point at the beginning of the result */
ptr = result;
while (n--) {
/* copy str to the result */
memcpy(ptr, str, str_len);
/* increment ptr to point at the next position we want to write to */
ptr += str_len;
}
/* null terminate the result. always null-terminate your strings
even if they are binary strings */
*ptr = '/0';
/* return result to the scripting engine without duplicating it*/
return_stringl(result, result_length, 0);
}
/* }}} */
现在要做的就是重新编译一下php，这样就完成了第一个php函数。
让我门检查函数是否真的工作。在最新编译过的php树下执行[2]下面的脚本：
你应该得到下面的结果：
thisisuseless
thisisuselessthisisuseless
thisisuselessthisisuselessthisisuseless
实例小结
你已经学会如何编写一个简单的php函数。回到本章的开头，我们提到用c编写php功能函数的两个主要的动机。第一个动机是用c实现一些算法来提高性能和扩展功能。前一个例子应该能够指导你快速上手这种类型扩展的开发。第二个动机是包裹三方函数库。我们将在下一步讨论。
包裹第三方的扩展
本节中你将学到如何编写更有用和更完善的扩展。该节的扩展包裹了一个c库，展示了如何编写一个含有多个互相依赖的php函数扩展。
动机 也许最常见的php扩展是那些包裹第三方c库的扩展。这些扩展包括mysql或oracle的数据库服务库，libxml2的 xml技术库，imagemagick 或gd的图形操纵库。
在本节中，我们编写一个扩展，同样使用脚本来生成骨架扩展，因为这能节省许多工作量。这个扩展包裹了标准c函数fopen(), fclose(), fread(), fwrite()和 feof().
扩展使用一个被叫做资源的抽象数据类型，用于代表已打开的文件file*。你会注意到大多数处理比如数据库连接、文件句柄等的php扩展使用了资源类型，这是因为引擎自己无法直接“理解”它们。我们计划在php扩展中实现的c api列表如下：
file *fopen(const char *path, const char *mode);
int fclose(file *stream);
size_t fread(void *ptr, size_t size, size_t nmemb, file *stream);
size_t fwrite(const void *ptr, size_t size, size_t nmemb, file *stream);
int feof(file *stream);
我们实现这些函数，使它们在命名习惯和简单性上符合php脚本。如果你曾经向php社区贡献过代码，你被期望遵循一些公共习俗，而不是跟随c库里的api。并不是所有的习俗都写在php代码树的coding_standards文件里。这即是说，此功能已经从php发展的很早阶段即被包含在php中，并且与c库api类似。php安装已经支持fopen(), fclose()和更多的php函数。
以下是php风格的api：
resource file_open(string filename, string mode)
file_open()接收两个字符串（文件名和模式），返回一个文件的资源句柄。
bool file_close(resource filehandle)
file_close()接收一个资源句柄，返回真/假指示是否操作成功。
string file_read(resource filehandle, int size)
file_read()接收一个资源句柄和读入的总字节数，返回读入的字符串。
bool file_write(resource filehandle, string buffer)
file_write接收一个资源句柄和被写入的字符串，返回真/假指示是否操作成功。
bool file_eof(resource filehandle)
file_eof()接收一个资源句柄，返回真/假指示是否到达文件的尾部。
因此，我们的函数定义文件——保存为ext/目录下的myfile.def——内容如下：
resource file_open(string filename, string mode)
bool file_close(resource filehandle)
string file_read(resource filehandle, int size)
bool file_write(resource filehandle, string buffer)
bool file_eof(resource filehandle)
下一步，利用ext_skel脚本在ext./ 原代码目录执行下面的命令：
./ext_skel --extname=myfile --proto=myfile.def
然后，按照前一个例子的关于编译新建立脚本的步骤操作。你会得到一些包含fetch_resource()宏行的编译错误，这样骨架脚本就无法顺利完成编译。为了让骨架扩展顺利通过编译，把那些出错行[3]注释掉即可。
资源 资源是一个能容纳任何信息的抽象数据结构。正如前面提到的，这个信息通常包括例如文件句柄、数据库连接结构和其他一些复杂类型的数据。
使用资源的主要原因是因为：资源被一个集中的队列所管理，该队列可以在php开发人员没有