PHP扩展开发常用宏介绍

定义函数实体

• PHP_FE <=> ZEND_FE(name, arg_info)

name: 函数名
arg_info: 函数参数定义信息

Example:

const zend_function_entry xml_functions[] = {
    PHP_FE(xml_parser_create,                   arginfo_xml_parser_create)
    PHP_FE(xml_parser_create_ns,                arginfo_xml_parser_create_ns)
    PHP_FE(xml_set_object,                      arginfo_xml_set_object)
    PHP_FE(xml_set_element_handler,             arginfo_xml_set_element_handler)
    PHP_FE(xml_set_character_data_handler,      arginfo_xml_set_character_data_handler)
    PHP_FE(xml_set_processing_instruction_handler,  arginfo_xml_set_processing_instruction_handler)
    PHP_FE(xml_set_default_handler,                 arginfo_xml_set_default_handler)
    PHP_FE(xml_set_unparsed_entity_decl_handler,arginfo_xml_set_unparsed_entity_decl_handler)
    PHP_FE(xml_set_notation_decl_handler,       arginfo_xml_set_notation_decl_handler)
    PHP_FE(xml_set_external_entity_ref_handler, arginfo_xml_set_external_entity_ref_handler)
    PHP_FE(xml_set_start_namespace_decl_handler,arginfo_xml_set_start_namespace_decl_handler)
    PHP_FE(xml_set_end_namespace_decl_handler,  arginfo_xml_set_end_namespace_decl_handler)
    PHP_FE(xml_parse,                           arginfo_xml_parse)
    PHP_FE(xml_parse_into_struct,               arginfo_xml_parse_into_struct)
    PHP_FE(xml_get_error_code,                  arginfo_xml_get_error_code)
    PHP_FE(xml_error_string,                    arginfo_xml_error_string)
    PHP_FE(xml_get_current_line_number,         arginfo_xml_get_current_line_number)
    PHP_FE(xml_get_current_column_number,       arginfo_xml_get_current_column_number)
    PHP_FE(xml_get_current_byte_index,          arginfo_xml_get_current_byte_index)
    PHP_FE(xml_parser_free,                     arginfo_xml_parser_free)
    PHP_FE(xml_parser_set_option,               arginfo_xml_parser_set_option)
    PHP_FE(xml_parser_get_option,               arginfo_xml_parser_get_option)
    PHP_FE(utf8_encode,                         arginfo_utf8_encode)
    PHP_FE(utf8_decode,                         arginfo_utf8_decode)
    PHP_FE_END
};

函数参数定义宏

最常用的就是下面三个, 定义在zend_API.h当中.

• ZEND_BEGIN_ARG_INFO_EX(name, _unused, return_reference, required_num_args)
• ZEND_END_ARG_INFO()
• ZEND_ARG_INFO(pass_by_ref, name)

ZEND_BEGIN_ARG_INFO_EX

name: 键名, 规范命名都是 函数名+arginfo, 也可以自己随意, 但推荐按照官方扩展的全名规范来

_unused: 这个估计是扩展字段, 预留给以后用的, 现在用不到, 一般传值为0

return_reference: 返回值是否是引用类型

required_num_args: 必须传值的数量

ZEND_END_ARG_INFO

无参数, 其实就是个花括号

ZEND_ARG_INFO

pass_by_ref: 是否为传引用
name: 参数名

Example:

ZEND_BEGIN_ARG_INFO_EX(arginfo_xml_parse_into_struct, 0, 0, 3)
    ZEND_ARG_INFO(0, parser)
    ZEND_ARG_INFO(0, data)
    ZEND_ARG_INFO(1, values)
    ZEND_ARG_INFO(1, index)
ZEND_END_ARG_INFO()

看看参数宏定义， 可以清晰地知道返回值为非引用类型, 函数有4个形参, 其中3个参数是必须传的, 最后一个参数index为可选参数.

注册常量

• REGISTER_NULL_CONSTANT(name, flags)
• REGISTER_BOOL_CONSTANT(name, bval, flags)
• REGISTER_LONG_CONSTANT(name, lval, flags)
• REGISTER_DOUBLE_CONSTANT(name, dval, flags)
• REGISTER_STRING_CONSTANT(name, str, flags)
• RREGISTER_STRINGL_CONSTANT(name, str, len, flags)
• CONST_CS
• CONST_PERSISTENT

REGISTER_LONG_CONSTANT

name: 注册的常量名
lval: 注册的常量值
flags: 常量标记的类型 (CONST_CS: 是否大小写区分, 一般都要写上; CONST_PERSISTENT: 是否持久化, 一般也都要写上)

一般在模块初始化函数内注册常量

Example:

PHP_MINIT_FUNCTION(gd)
{
    .....
    REGISTER_LONG_CONSTANT("IMG_GIF", 1, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_JPG", 2, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_JPEG", 2, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_PNG", 4, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_WBMP", 8, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_XPM", 16, CONST_CS | CONST_PERSISTENT);
    REGISTER_LONG_CONSTANT("IMG_WEBP", 32, CONST_CS | CONST_PERSISTENT);
    ...
}

解析用户参数新版本

解析参数有两种方式, 推荐使用新版本的

旧方法:

zend_parse_parameters(int num_args, const char *type_spec, …)

num_args: 参数总数
type_spec: 指定参数的类型
… 接收参数的容器变量们

Example:

if (zend_parse_parameters(ZEND_NUM_ARGS(), "S|lsb", &text, &linelength, &breakchar, &breakchar_len, &docut) == FAILURE) {
        return;
    }

新方法:

• ZEND_PARSE_PARAMETERS_START(min_num_args, max_num_args)
• ZEND_PARSE_PARAMETERS_END()
• Z_PARAM_ARRAY <=> a
• Z_PARAM_ARRAY_OR_OBJECT <=> A
• Z_PARAM_BOOL <=> b
• Z_PARAM_CLASS <=> C
• Z_PARAM_DOUBLE <=> d
• Z_PARAM_FUNC <=> f
• Z_PARAM_ARRAY_HT <=> h
• Z_PARAM_ARRAY_OR_OBJECT_HT <=> H
• Z_PARAM_LONG <=> l
• Z_PARAM_STRICT_LONG <=> L
• Z_PARAM_OBJECT <=> o
• Z_PARAM_OBJECT_OF_CLASS <=> O
• Z_PARAM_PATH <=> p
• Z_PARAM_PATH_STR <=> P
• Z_PARAM_RESOURCE <=> r
• Z_PARAM_STRING <=> s
• Z_PARAM_STR <=> S
• Z_PARAM_ZVAL <=> z
• Z_PARAM_OPTIONAL <=> |

Example:

ZEND_PARSE_PARAMETERS_START(1, 4)
    Z_PARAM_STR(text)
    Z_PARAM_OPTIONAL
    Z_PARAM_LONG(linelength)
    Z_PARAM_STRING(breakchar, breakchar_len)
    Z_PARAM_BOOL(docut)
ZEND_PARSE_PARAMETERS_END();

新版本的可读性更强一些.