PHP内核介绍及扩展开发指南——Extensions 的编写（二）

1.2.2 底层方法

大部分情况下，使用标准方法就可以了，但有些函数可能需要处理变参，标准方法对此无能为力(*)。此时，只有使用更加原始的方法——直接获取zval。Zend提供了如下的API：


param_count是希望获取的参数数目，这个值不得大于ZEND_NUM_ARGS()，否则函数出错。argument_array是一个zval**类型的数组，用于接收参数。
这个函数只是简单的返回zval，为了使用它们，我们需要自己访问其成员。首先是获取参数类型，这可以通过zval.type值来判断，可用的type见1.1.1节。之后是获取该type对应的值，我们可以直接访问zval的成员，比如zval.value.lval就是long值，但更方便的方法是使用Zend提供的宏：


一个比较特殊的宏是Z_BVAL，它不是简单的返回值，而是进行了类型转换。另外，这些宏都有相应的xxx_P和xxx_PP版本，用于访问zval*和zval**。
有时，用户传入参数的类型并不是我们期望的，这就需要手动进行类型转换了。为此，Zend提供了如下几个函数：
convert_to_boolean_ex()
convert_to_long_ex()
convert_to_double_ex()
convert_to_string_ex()
convert_to_array_ex()
convert_to_object_ex()
convert_to_null_ex()
这些函数可将目标zval转换成指定类型，它接收zval**作为参数，为什么不用zval*呢？这是因为，这些函数有一个额外的步骤，它如果发现传入的zval不是引用类型的，并且需要执行类型转换，则会首先执行Copy-On-Write，并对副本施行转换，因此，为了返回副本必须使用zval**作为参数。如果zval是引用型的，则转换直接作用于目标zval结构。
如果无法转换，这些函数就会将zval设置为目标类型的虚值，比如0、FALSE、空串等，因此函数总会成功返回。
这些函数的非ex版本不执行zval分离，而是直接作用于原zval,因此参数类型是zval*。

1.2.2 引用传递

函数参数的传递也是采用的引用计数方式，函数栈中存放的只是zval**，它很可能和几个变量共享一个zval。
显然，对于引用型的zval，我们可以直接进行写入操作；而对于非引用型的zval，并且其refcount大于1时，如果要进行写入操作，就必须执行zval分离（参见1.1.3）。refcount等于1的情况是因为Zend引擎已经执行了zval状态切换（参见1.1.4情况II），我们得到的是自己独占的zval，可以直接写入。
关于传入的zval是否引用，可以通过zval.is_ref来判断，或者使用宏PZVAL_IS_REF(zval*)。对于zval分离，可以使用宏SEPARATE_ZVAL(zval**)，它会自动判断refcount，并且将新zval的地址填充到参数里。

1.2.4 编译检查(TODO)

上面几节介绍了如何在我们的函数中对参数进行检查，也就是运行时检查，这为函数的编写带来了一些负担，代码也不够简洁。为此，Zend提供了编译时检查机制，允许我们指定函数原型，如果用户不按规定调用，则会报错并且跳过该函数，因此，我们的函数总能得到期望的参数。

1.3返回值

从C函数向PHP返回值，并不能使用通常的return语句，导出函数的原型也说明了这一点：


因此，Zend将返回值地址作为参数传给我们，return_value是Zend为我们预先创建的一个标准zval结构，相当于一个局部变量，用户获得返回值时就相当于对return_value进行赋值操作，我们只需填充它即可；return_value_used表明用户是否使用了返回值，0表明没有使用返回值，当函数结束后return_value的refcount将被减为0，并被销毁，因此，这种情况下完全可以不处理返回值；return_value_ptr用于返回引用，它需要和zend_function_entry.arg_info联合使用，通常都是NULL。
Zend提供了一组宏用于填充return_value：


这些宏将在填充完return_value后，执行return语句。如果不想return，可以改用相应RETURN_xxx宏的RETVAL_xxx版本。

1.3.1 返回引用

默认情况下，return_value_ptr是NULL，而当指定返回引用后（参见2.2.4），zend将采用*return_value_ptr作为返回值。初始状态下，return_value 依然指向一个临时zval，同时 *return_value_ptr = return_value。
通常应该把return_value销毁，并且将*return_value_ptr设为将要返回的zval*，注意要加加引用计数，因为这相当于将该zval赋值给一个用作返回值的临时变量，函数返回后，Zend会减减引用计数。
示例程序：


1.4启动和终止函数
Zend允许模块在加载和卸载时收到通知，以进行初始化和清除工作，我们要做的就是把相应函数传递给Zend，它会在合适的时机自动调用。2.1.3节里留下的五个NULL就是用于这个目的，它们都是函数指针，最后一个用于配合phpinfo()来显示模块信息，在此忽略，只看其他四个。
Zend提供了如下四个宏，分别用于声明对应的函数：


这些宏的用法和ZEND_FUNCTION宏一样（参见2.1.1），展开后就是声明了特定原型的函数，其参数module可以是任意的，但最好使用模块名称。这些函数的参数中，对我们有用的是int module_number，它是模块号，全局唯一，后面会提到其用处。
在声明和实现相应函数时，都应该使用这些宏。最后，需要把这些函数填写到zend_module_entry里（参见2.1.3），可按顺序使用如下的宏，这些宏生成相应的函数名称：


1.5调用PHP函数
有时我们需要在模块中调用用户指定的函数，比如我们实现了sort这样的函数，并且允许用户指定比较函数。这可以使用如下的Zend函数：


第一个参数是HashTable，在1.2.3节提到Zend使用HashTable来存储PHP函数，function_table用于指定从哪个HashTable中获取函数。通常应该用CG(function_table)，展开就是compiler_globals.function_table，compiler_globals是一个用来存储编译器数据的全局数据结构（与其对应的还有个EG宏，即executor_globals，它用来存储执行器数据）。compiler_globals.function_table里面存储了所有我们可以在PHP页面里面调用的函数，包括Zend内建函数、PHP标准库函数、模块导出的函数以及用户使用PHP代码定义的函数。
object_pp是一个对象，当指定该值时，Zend会从对象的函数表中获取函数，这里不予讨论，总是设为NULL。
function_name必须是string型的zval，存储我们希望调用的函数的名称。为什么使用zval而不是直接用char*，是因为Zend考虑到大部分情况下，我们都是从用户那获得参数，然后再调用call_user_function_ex的，这样就可以不作处理直接把用户参数传给该函数。当然，我们也可以手动创建一个string型zval传给它。
retval_ptr_ptr用于获取函数的返回值，Zend执行完指定的函数后，它就将返回值的指针填充到这里。
param_count和params用于指定函数的参数，params是个zval **这点可能让人感到奇怪，但考虑到该函数的常见用法（见下面的示例）以及2.2.2节关于函数参数的介绍，就一点也不奇怪了。
no_separation用于指定是否在必要时执行zval分离（参见1.1.3），这在写入非引用zval时发生。应该总是将其设为0，表示执行zval分离，否则可能破坏数据。
symbol_table用于指定目标函数的active_symbol_table（参见1.2.3），通常应该使用NULL，这样Zend会为目标函数生成一个空的符号表。
说了这么多，该动动手了，下面的程序片段简单实现了PHP API call_user_func的功能：



未完待续哦~