[通译][php扩展和嵌入式]第10章-php4的对象

void php_sample2_inherit_from_class(zend_class_entry *ce,
                        zend_class_entry *parent_ce) {
    zend_hash_merge(&ce->function_table,
            &parent_ce->function_table, (void (*)(void *))function_add_ref,
            NULL, sizeof(zval*), 0);
    ce->parent = parent_ce;
    if (!ce->handle_property_get) {
        ce->handle_property_get =
                parent_ce->handle_property_get;
    }
    if (!ce->handle_property_set) {
        ce->handle_property_set =
                parent_ce->handle_property_set;
    }
    if (!ce->handle_function_call) {
        ce->handle_function_call =
                parent_ce->handle_function_call;
    }
    if (!zend_hash_exists(&ce->function_table,
                ce->name, ce->name_length + 1)) {
        zend_function *fe;
        if (zend_hash_find(&parent_ce->function_table,
                parent_ce->name, parent_ce->name_length + 1,
                (void**)fe) == SUCCESS) {
            zend_hash_update(&ce->function_table,
                ce->name, ce->name_length + 1,
                fe, sizeof(zend_function), NULL);
            function_add_ref(fe);
        }
    }
}

定义这样一个函数, 你就可以在MINIT中zend_register_internal_class下面对其进行调用:

INIT_CLASS_ENTRY(ce, "Sample2_FirstClass", NULL);
/* 假定php_saple2_ancestor是一个已经注册的zend_class_entry */
php_sample2_firstclass_entry =
        zend_register_internal_class(&ce TSRMLS_CC);
php_sample2_inherit_from_class(php_sample2_firstclass_entry
                            ,php_sample2_ancestor);

尽管这种方式的继承可以工作, 但还是应该避免ZE1中的继承, 因为它并没有设计内部对象的继承处理. 对于php中的多数OOP实践, ZE2和它修订的对象模型是健壮的, 鼓励所有的OOP相关任务都直接使用它来处理.

使用实例工作

和其它用户空间变量一样, 对象存储在zval *容器中. 在ZE1中, zval *包含了一个HashTable *用于保存属性, 以及一个zend_class_entry *指针, 指向类的定义. 在ZE2中, 这些值被一个句柄表替代, 增加了一个数值的对象ID, 它和资源ID的用法类似.

很幸运, ZE1和ZE2的这些差异被第2章"变量的里里外外"中介绍的Z_*()族宏隐藏了, 因此在你的扩展中不需要关心这些. 下表10.1列出了两个ZE1的宏, 与非OOP的相关宏一致, 它们也有对应的_P和_PP版本, 用来处理一级或两级间访.

创建实例

大部分时间, 你的扩展都不需要自己创建实例. 而是用户空间调用new关键字创建实例并调用你的类构造器.

但你还是有可能需要创建实例, 比如在工厂方法中, ZEND_API中的object_init_ex(zval *val, zend_class_entry *ce)函数可以用于将对象实例初始化到变量中.

要注意, object_init_ex()函数并不会调用构造器. 当在内部函数中实例化对象时, 构造器必须手动调用. 下面的过程函数重演了new关键字的功能逻辑:

PHP_FUNCTION(sample2_new)
{
    int argc = ZEND_NUM_ARGS();
    zval ***argv = safe_emalloc(sizeof(zval**), argc, 0);
    zend_class_entry *ce;
    if (argc == 0 ||
        zend_get_parameters_array_ex(argc, argv) == FAILURE) {
        efree(argv);
        WRONG_PARAM_COUNT;
    }
    /* 第一个参数是类名 */
    SEPARATE_ZVAL(argv[0]);
    convert_to_string(*argv[0]);
    /* 类名存储为小写 */
    php_strtolower(Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]));
    if (zend_hash_find(EG(class_table),
            Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]) + 1,
            (void**)&ce) == FAILURE) {
        php_error_docref(NULL TSRMLS_CC, E_WARNING,
            "Class %s does not exist.",
            Z_STRVAL_PP(argv[0]));
        zval_ptr_dtor(argv[0]);
        efree(argv);
        RETURN_FALSE;
    }
    object_init_ex(return_value, ce);
    /* 如果有构造器则调用, 额外的参数将传递给构造器 */
    if (zend_hash_exists(&ce->function_table,
            Z_STRVAL_PP(argv[0]),Z_STRLEN_PP(argv[0]) + 1)) {
        /* 对象有构造器 */
        zval *ctor, *dummy = NULL;

        /* 构造器名字是类名 */
        MAKE_STD_ZVAL(ctor);
        array_init(ctor);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
        if (call_user_function_ex(&ce->function_table,
                NULL, ctor,
                &dummy, /* 不关心返回值 */
                argc - 1, argv + 1, /* 参数 */
                0, NULL TSRMLS_CC) == FAILURE) {
            php_error_docref(NULL TSRMLS_CC, E_WARNING,
                 "Unable to call constructor");
        }
        if (dummy) {
            zval_ptr_dtor(&dummy);
        }
        zval_ptr_dtor(&ctor);
    }
    zval_ptr_dtor(argv[0]);
    efree(argv);
}

不要忘了在php_sample2_functions中增加一个引用. 它是你的扩展的过程函数列表, 而不是类方法的列表. 为了使用php_strtolower()函数, 还需要增加#include "ext/standard/php_string.h".

这个函数是目前你实现的最复杂的一个, 其中有几个全新的特性. 首先就是SEPARATE_ZVAL(), 实际上它的功能你已经实现过很多次, 利用zval_copy_ctor()赋值值到一个临时的结构体, 避免修改原始的内容. 不过它是一个宏版本的封装.

php_strtolower()用于将类名转换为小写, 这样做是为了达到php类名和函数名不区分大小写的目的. 这只是附录B中列出的众多PHPAPI工具函数的其中一个.

EG(class_table)是一个全局变量, 所有的zend_class_entry定义都注册到它里面. 要注意的是在ZE1(php4)中这个HashTable存储了一级间访的zend_class_entry *结构体. 而在ZE2(php5)中, 它被存储为两级间访. 这应该不会是一个问题, 因为对这个HashTable的直接访问并不常见, 但知道这一点总归是有好处的.

call_user_function_ex()是你将在第20章"高级嵌入式"中看到的ZENDAPI调用的一部分. 这里你将从zend_get_parameters_ex()接收到的zval **参数栈第一个元素拿走, 这样做就是为了原封不动的将剩余的参数传递给构造器.

译注: 原著中的代码在译者的环境(php-5.4.9)中不能运行, 需要将zend_class_entry *ce修改为二级间访. 下面给出译者测试通过的代码.

PHP_FUNCTION(sample_new)
{
    int                 argc    = ZEND_NUM_ARGS();
    zval                ***argv = safe_emalloc(sizeof(zval **), argc, 0); 
    zend_class_entry    **ce;       /* 译注: 这里在译者的环境(php-5.4.9)是二级间访 */

    /* 数组方式读取所有传入参数 */
    if ( argc == 0 ||  
            zend_get_parameters_array_ex(argc, argv) == FAILURE ) { 
        efree(argv);
        WRONG_PARAM_COUNT;
    }   

    /* 隔离第一个参数(隔离为了使下面的类型转换不影响原始数据) */
    SEPARATE_ZVAL(argv[0]);
    /* 将第一个参数转换为字符串类型, 并转为小写(因为php的类名是不区分大小写的) */
    convert_to_string(*argv[0]);
    php_strtolower(Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]));
    /* 在类的HashTable中查找提供的类是否存在, 如果存在, ce中就得到了对应的zend_class_entry * */
    if ( zend_hash_find(EG(class_table), Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]) + 1, (void **)&ce) == FAILURE ) { 
        php_error_docref(NULL TSRMLS_CC, E_WARNING, "Class %s does not exist.", Z_STRVAL_PP(argv[0]));
        zval_ptr_dtor(argv[0]);
        efree(argv);
        RETURN_FALSE;
    }   

    /* 将返回值初始化为查找到的类的对象 */
    object_init_ex(return_value, *ce);
    /* 检查类是否有构造器 */
    if ( zend_hash_exists(&(*ce)->function_table, Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]) + 1) ) { 
        zval    *ctor, *dummy = NULL;

        /* 将ctor构造为一个数组, 对应的用户空间形式为: array(argv[0], argv[0]), 
         * 实际上对应于用户空间调用类的静态方法时$funcname的参数形式:
         * array(类名, 方法名)
         */
        MAKE_STD_ZVAL(ctor);
        array_init(ctor);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
        /* 调用函数 */
        if ( call_user_function_ex(&(*ce)->function_table, NULL, ctor, &dummy, argc - 1, argv + 1, 0, NULL TSRMLS_CC) == FAILURE ) { 
            php_error_docref(NULL TSRMLS_CC, E_WARNING, "Unable to call constructor");
        }   
        /* 如果有返回值直接析构丢弃 */
        if ( dummy ) {
            zval_ptr_dtor(&dummy);
        }
        /* 析构掉临时使用(用来描述所调用方法名)的数组 */
        zval_ptr_dtor(&ctor);
    }
    /* 析构临时隔离出来的第一个参数(类名) */
    zval_ptr_dtor(argv[0]);
    /* 释放实参列表空间 */
    efree(argv);
}

接受实例

有时你的函数或方法需要接受用户空间的对象参数. 对于这种目的, zend_parse_parameters()提供了两种格式的修饰符. 第一种是o(小写字母o), 它将验证传递的参数是否是对象, 并将它设置到传递的zval **中. 下面是这种方式的一个简单的用户空间函数示例, 它返回传入对象的类名.

PHP_FUNCTION(sample2_class_getname)
{
    zval *objvar;
    zend_class_entry *objce;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o",
                                &objvar) == FAILURE) {
        RETURN_NULL();
    }
    objce = Z_OBJCE_P(objvar);
    RETURN_STRINGL(objce->name, objce->name_length, 1);
}

PHP_FUNCTION(sample2_reload)
{
    zval *objvar;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O",
        &objvar, php_sample2_firstclass_entry) == FAILURE) {
        RETURN_NULL();
    }
    /* 调用假想的"reload"函数 */
    RETURN_BOOL(php_sample2_fc_reload(objvar TSRMLS_CC));
}

zval **fooval;
if (zend_hash_find(Z_OBJPROP_P(rcvdclass),
        "foo", sizeof("foo"), (void**)&fooval) == FAILURE) {
    /* $rcvdclass->foo doesn't exist */
    return;
}

PHP_NAMED_FUNCTION(php_sample2_fc_ctor)
{
    /* 为了简洁, 同时演示函数名可以是任意的, 这里实现的函数名并不是类名 */
    zval *objvar = getThis();

    if (!objvar) {
        php_error_docref(NULL TSRMLS_CC, E_WARNING,
                        "Constructor called statically!");
        RETURN_FALSE;
    }

    add_property_long(objvar, "life", 42);
    add_property_double(objvar, "pi", 3.1415926535);
    /* 构造器的返回值会被忽略(请回顾前面构造器的例子) */
}

PHP_NAMED_FE(sample2_firstclass, php_sample2_fc_ctor, NULL)

PHP_FUNCTION(sample_new)
{
    int                 argc    = ZEND_NUM_ARGS();
    zval                ***argv = safe_emalloc(sizeof(zval **), argc, 0); 
    zend_class_entry    **ce;       /* 译注: 这里在译者的环境(php-5.4.9)是二级间访 */

    /* 数组方式读取所有传入参数 */
    if ( argc == 0 ||  
            zend_get_parameters_array_ex(argc, argv) == FAILURE ) { 
        efree(argv);
        WRONG_PARAM_COUNT;
    }   

    /* 隔离第一个参数(隔离为了使下面的类型转换不影响原始数据) */
    SEPARATE_ZVAL(argv[0]);
    /* 将第一个参数转换为字符串类型, 并转为小写(因为php的类名是不区分大小写的) */
    convert_to_string(*argv[0]);
    php_strtolower(Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]));
    /* 在类的HashTable中查找提供的类是否存在, 如果存在, ce中就得到了对应的zend_class_entry * */
    if ( zend_hash_find(EG(class_table), Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]) + 1, (void **)&ce) == FAILURE ) { 
        php_error_docref(NULL TSRMLS_CC, E_WARNING, "Class %s does not exist.", Z_STRVAL_PP(argv[0]));
        zval_ptr_dtor(argv[0]);
        efree(argv);
        RETURN_FALSE;
    }   

    /* 将返回值初始化为查找到的类的对象 */
    object_init_ex(return_value, *ce);
    /* 检查类是否有构造器 */
    if ( zend_hash_exists(&(*ce)->function_table, Z_STRVAL_PP(argv[0]), Z_STRLEN_PP(argv[0]) + 1) ) { 
#define DYNAMIC_CONSTRUCTOR
#ifndef DYNAMIC_CONSTRUCTOR
        zval    *ctor;
#endif
        zval    *dummy = NULL;

#ifndef DYNAMIC_CONSTRUCTOR
        /* 将ctor构造为一个数组, 对应的用户空间形式为: array(argv[0], argv[0]), 
         * 实际上对应于用户空间调用类的静态方法时$funcname的参数形式:
         * array(类名, 方法名)
         */
        MAKE_STD_ZVAL(ctor);
        array_init(ctor);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
        zval_add_ref(argv[0]);
        add_next_index_zval(ctor, *argv[0]);
#endif
        /* 调用函数 */
        if ( call_user_function_ex(&(*ce)->function_table,
#ifndef DYNAMIC_CONSTRUCTOR
                NULL, ctor,
#else
                &return_value, *argv[0],
#endif
                &dummy, argc - 1, argv + 1, 0, NULL TSRMLS_CC) == FAILURE ) {
            php_error_docref(NULL TSRMLS_CC, E_WARNING, "Unable to call constructor");
        }
        /* 如果有返回值直接析构丢弃 */
        if ( dummy ) {
            zval_ptr_dtor(&dummy);
        }
#ifndef DYNAMIC_CONSTRUCTOR
        /* 析构掉临时使用(用来描述所调用方法名)的数组 */
        zval_ptr_dtor(&ctor);
#endif
    }
    /* 析构临时隔离出来的第一个参数(类名) */
    zval_ptr_dtor(argv[0]);
    /* 释放实参列表空间 */
    efree(argv);
}