Detailed explanation of examples of passing parameters and obtaining parameters in the extension function of PHP extension

Preface

After the automatic generation of the extension framework of the PHP extension in the previous article, I have an overall understanding of the PHP extension framework. Basically, it can be said that I have a certain grasp of how to write PHP extensions and the key points. But the key lies in how to write the PHP_FUNCTION function.
This article mainly records how PHP passes parameters when calling an extension, and how the extension function receives the call. Treat it as your own memo

Text

1.zend_parse_parameters

To obtain the parameters passed by the function, you can use the zend_parse_parameters function. Careful students will find that the officially generated default function is also Use this function to receive parameters.

How to use this function?

First of all, you can use this reading as PHP's scanf. (If you are not familiar with this function, please feel free to read it here)

zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, &参数1,&参数2…);

The first parameter is the number of parameters passed to the function. The usual approach is to pass it ZEND_NUM_ARGS(). (ZEND_NUM_ARGS() to express "as many as there are parameters" passed in) This is a macro that represents the total number of parameters passed to the function.

The second parameter is for thread safety, always pass the TSRMLS_CC macro.

The third parameter is a string that specifies the parameter type expected by the function, followed by a list of variables that need to be updated with the parameter value. Since PHP is a weakly typed language, it uses loose variable definitions and dynamic type judgment, while the C language is strongly typed, and zend_parse_parameters() is to convert different types of parameters into the expected type. (When the actual value cannot be coerced into the expected type, a warning will be issued)

The fourth, fifth, and nth parameters are all the values ​​of the values ​​to be passed in.

Detailed explanation of the third parameter

Regarding the third parameter, here is a parameter list for selection:

Type specifier	Corresponding C type	Description
l	long	Symbol Integer
d	double	Floating point number
s	char *, int	Binary string, length
b	zend_bool	Logical type (1 or 0)
r	zval *	Resources (file pointers, database connections, etc.)
a	zval *	Associative array
o	zval *	Object of any type
O	zval *	Object of the specified type. The class type of the target object needs to be provided
z	zval *	zval without any operation

There are two points that need special attention here
1. The c type corresponding to the string type here has two parameters. Yes. This shows that when using the zend_parse_parameters() function, you need to use it like this:

zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s",&name, &name_len)

One represents the string content, and the other is the string length.

2. You need to know roughly, what is zval?
zval is the value container of Zend engine. Regardless of whether the variable is a boolean, string, or any other type, its information is always contained in a zval union. Let’s take a look at the structure of zval:

typedef union _zval {    long lval;    double dval;    struct {        char *val;        int len;

    } str;

    HashTable *ht;

    zend_object_value obj;

} zval;

ps: I won’t explain typedef because I found that someone has already written it very well. Please click on the summary of the usage of typedef

Here it is Involves three additional usages to enhance our ability to receive parameters:

Symbol	Explanation
|	The parameters before it are all necessary, and the parameters after it are not necessary, that is, they have default values.
!	If a null variable in PHP language is received, it will be directly converted into NULL in C language instead of encapsulating it into a zval of IS_NULL type. .
/	If the passed variable shares a zval with other variables and is not a reference, forced separation is performed, and the new zval's is_ref__gc==0, and refcount__gc==1.

“|”和”!”将在下文有具体例子讲解，关于”/”虽然大概懂意思，但没想到具体的例子。

走一波与php的交互

正常的样子

在PHP中

<?phpfunction my_function($msg) {
    echo "我收到参数啦： {$msg}!\n";
}
my_function(&#39;咖啡色的羊驼&#39;);

如果my_function写成PHP扩展：

ZEND_FUNCTION(my_function) {
    char *msg;
    int msg_len;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s",&msg, &msg_len) == FAILURE){
        RETURN_NULL();
    }
    php_printf("我收到参数啦：");
    PHPWRITE(msg, msg_len);
    php_printf("!\n");
}

两个参数的样子

在PHP中

<?phpfunction my_function($email, $msg) {
    echo "我收到参数啦： {$email}、 {$msg}!\n";
}
my_function(&#39;123456@qq.com&#39;, &#39;咖啡色的羊驼&#39;);

如果my_function写成PHP扩展：

ZEND_FUNCTION(my_function) {
    char *email;
    int email_len;
    char *msg;
    int msg_len;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "ss",&msg, &msg_len,&email, &email_len) == FAILURE){
        RETURN_NULL();
    }
    php_printf("我收到参数啦：");
    PHPWRITE(email, email_len);
    PHPWRITE(msg, msg_len);
    php_printf("!\n");
}

两个参数,其中一个可选且有默认值

<?phpfunction my_function($email, $msg = &#39;咖啡色的羊驼&#39;) {
    echo "我收到参数啦： {$email}、 {$msg}!\n";
}
my_function(&#39;123456@qq.com&#39;);

如果my_function写成PHP扩展：

ZEND_FUNCTION(my_function) {
    char *email;
    int email_len;
    char *msg = "咖啡色的羊驼";
    int msg_len = sizeof("咖啡色的羊驼") - 1;

    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|s",&msg, &msg_len,&email, &email_len) == FAILURE){
        RETURN_NULL();
    }
    php_printf("我收到参数啦：");
    PHPWRITE(email, email_len);
    PHPWRITE(msg, msg_len);
    php_printf("!\n");
}

这里说明了”｜”的使用

参数为null时，省内存的写法

先来不省的写法

ZEND_FUNCTION(my_function) {
    zval *val;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z",&val) == FAILURE) {
        RETURN_NULL();
    }
}

省内存

ZEND_FUNCTION(my_function) {
    zval *val;
    if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "z!",&val) == FAILURE) {
        RETURN_NULL();
    }
}

这里例子用上了”!”，每个zval，包括IS_NULL型的zval，都需要占用一定的内存空间，需要cpu的计算资源来为它申请内存、初始化，并在它们完成工作后释放掉。但是很多代码都都没有意识到这一点。有很多代码都会把一个null型的值包裹成zval的IS_NULL类型，在扩展开发里这种操作是可以优化的，我们可以把参数接收成C语言里的NULL。
所以就差了一个！，第二个例子就更省了内存。

2.zend_get_arguments()

用法

例子是最好的用法讲解，上例子：

ZEND_FUNCTION(my_function) {
    zval *email;    if (zend_get_parameters(ZEND_NUM_ARGS(), 1, &email)== FAILURE) {
        php_error_docref(NULL TSRMLS_CC, E_WARNING,"至少需要一个参数");
        RETURN_NULL();
    }
    // ... }

区别与特点

1.能够兼容老版本的PHP，并且只以zval为载体来接收参数。
2.直接获取，而不做解析，不会进行类型转换，所有的参数在扩展实现中的载体都需要是zval类型的。
3.接受失败的时候，不会自己抛出错误，也不能方便的处理有默认值的参数。
4.会自动的把所有符合copy-on-write的zval进行强制分离，生成一个崭新的copy送到函数内部。

综合评价：还是用zend_parse_parameters吧，这个函数了解下即可，不给力。

3.zend_get_parameters_ex()

用法

ZEND_FUNCTION(my_function) {
    zval **msg;    if (zend_get_parameters_ex(1, &msg) == FAILURE) {
        php_error_docref(NULL TSRMLS_CC, E_WARNING,"至少需要一个参数");
        RETURN_NULL();
    }
    // ...}

不需要ZEND_NUM_ARGS()作为参数，因为它是在是在后期加入的，那个参数已经不再需要了。

区别与特点

1.此函数基本同zend_get_parameters()。
2.唯一不同的是它不会自动的把所有符合copy-on-write的zval进行强制分离，会用到老的zval的特性

综合评价：极端情况下可能会用到，这个函数了解下即可。

zend_get_parameter_**

这个包括：zend_get_parameters_array_ex()和zend_get_parameters_array()

用法

ZEND_FUNCTION(var_dump) {
    int i, argc = ZEND_NUM_ARGS();
    zval ***args;

    args = (zval ***)safe_emalloc(argc, sizeof(zval **), 0);
    if (ZEND_NUM_ARGS() == 0 || zend_get_parameters_array_ex(argc, args) == FAILURE) {
        efree(args);
        WRONG_PARAM_COUNT;
    }
    for (i=0; i<argc; i++) {
        php_var_dump(args[i], 1 TSRMLS_CC);
    }
    efree(args);
}

这个有点复杂，需要解释一下：
程序首先获取参数数量，然后通过safe_emalloc函数申请了相应大小的内存来存放这些zval**类型的参数。这里使用了zend_get_parameters_array_ex()函数来把传递给函数的参数填充到args中。
是的
这个参数专门用于解决像php里面的var_dump的一样，可以无限传参数进去的函数的实现

区别与特点

1.用于应对无限参数的扩展函数的实现。
2.zend_get_parameters_array与zend_get_parameters_array_ex唯一不同的是它将zval*类型的参数填充到args中，并且需要ZEND_NUM_ARGS()作为参数。

综合评价:当遇到确实需要处理无限参数的时候，真的要用这个函数了。zend_parse_parameters真的做不到啊～

总结

抛开一切，最少也要学会zend_parse_parameters()的用法。好的。扩展函数传参数的技能get了。

The above is the detailed content of Detailed explanation of examples of passing parameters and obtaining parameters in the extension function of PHP extension. For more information, please follow other related articles on the PHP Chinese website!