编程

PHP 底层原理之 Zval 强制类型转换

4 2026-11-18 23:35:00

类型转换及操作

类型转换

在许多情况下,你期望接收到的zval(值)是特定类型的。在这种情况下,你可以严格检查是否为期望的类型:

if (Z_TYPE_P(val) != IS_STRING) {
    zend_type_error("Expected string");
    return;
}

或者,你可以执行类型转换到所需的类型。类型转换有两种方式:第一种是使用 convert_to_* 函数之一来实际更改 zval 的类型:

convert_to_string(val);
// Z_TYPE_P(val) == IS_STRING is guaranteed here.

对于所有其他可以进行有意义类型转换的类型,也存在类似的功能:

void convert_to_null(zval *op);
void convert_to_boolean(zval *op);
void convert_to_long(zval *op);
void convert_to_double(zval *op);
void convert_to_string(zval *op);
void convert_to_array(zval *op);
void convert_to_object(zval *op);

此外,convert_scalar_to_number() 函数可用于将 zval 转换为整数或浮点数,但需要注意的是,数组将保持数组的形式:

convert_scalar_to_number(val);
switch (Z_TYPE_P(val)) {
    case IS_LONG:
        php_printf("Long: " ZEND_LONG_FMT "\n", Z_LVAL_P(val));
        break;
    case IS_DOUBLE:
        php_printf("Long: %H\n", Z_DVAL_P(val));
        break;
    case IS_ARRAY:
        php_printf("Array\n");
        break;
    ZEND_EMPTY_SWITCH_DEFAULT_CASE()
}

由于 convert_to_* 会就地修改 zval,因此需要注意保持写时复制的语义。一个常见的错误是编写如下代码:

zval *val;
ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(array), val) {
    convert_to_string(val);
    // Use val as string.
}

在这里,我们想要遍历一个数组,并将所有元素都视为字符串。然而,由于 convert_to_string() 函数是就地操作的,这意味着数组实际上会被修改。因此,只有当你唯一拥有该数组时,这段代码才是合法的。否则,有必要先进行分离:

zval *val;
SEPARATE_ARRAY(array);
ZEND_HASH_FOREACH_VAL(Z_ARRVAL_P(array), val) {
    convert_to_string(val);
    // Use val as string.
}

第二组转换 API 通过返回转换后的值,而不是改变 zval 本身的类型,从而避免了这个问题。在可以使用的情况下,这通常更方便、更高效且更安全(就写时复制而言)。在转换为布尔值、整数和浮点数时,我们只需接收一个 bool、zend_long 或 double 结果即可:

bool b = zend_is_true(val);
zend_long l = zval_get_long(val);
double d = zval_get_double(val);

对于字符串,我们接收一个 zend_string * 结果,之后必须释放它。如果值已经是字符串,则只会增加引用计数。如果不是字符串,它将返回一个现有的内部字符串,或者分配一个新的字符串:

zend_string *str = zval_get_string(val);
// Do something with str.
zend_string_release(str);

对于这种临时使用的情况,我们并不保留对 str 的长期引用,因此存在一个额外的优化 API:

zend_string *tmp_str;
zend_string *str = zval_get_tmp_string(val, &tmp_str);
// Do something with str.
zend_tmp_string_release(tmp_str);

此 API 的工作方式与 zval_get_string() 相同,但在值已经是字符串的常见情况下,避免了引用计数的增减。

特别是在转换为字符串时,还有一个额外的问题需要考虑:__toString() 方法可能会抛出异常(实际上,转换为整数和浮点数时也可能抛出异常,但这个问题通常会被忽略)。可以通过在字符串转换后检查 EG(exception) 来处理:

zend_string *str = zval_get_string(val);
if (EG(exception)) {
    // zend_string_release(str) is safe, but not necessary here.
    return;
}
zend_string_release(str);

然而,处理这种情况更地道、更高效的方法是使用这些函数的 try 变体,这些变体会在其返回值中指示是否抛出了异常:

if (!try_convert_to_string(val)) {
    // Exception thrown.
    return;
}

zend_string *str = zval_try_get_string(val);
if (!str) {
    // Exception thrown.
    return;
}
zend_string_release(str);

zend_string *tmp_str;
zend_string *str = zend_try_get_tmp_string(val, &tmp_str);
if (!str) {
    // Exception thrown.
    return;
}
zend_tmp_string_release(tmp_str);

操作

像 $op1 + $op2 这样的用户空间操作,在内部是通过相应的函数(如 add_function())来实现的,这些函数接受一个结果输出参数,后跟输入操作数:

zval *op1 = /* ... */, *op2 = /* ... */;
zval result;
if (add_function(&result, op1, op2) == FAILURE) {
    // Exception thrown.
    return;
}
// Do something with result.
zval_ptr_dtor(&result);

需要注意的是,这些函数在实践中很少使用,因为大多数代码都是处理特定类型的 zval,而不是操作完全任意的值。完整的函数集如下

zend_result add_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 + $op2 */
zend_result sub_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 - $op2 */
zend_result mul_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 * $op2 */
zend_result pow_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 ** $op2 */
zend_result div_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 / $op2 */
zend_result mod_function(zval *result, zval *op1, zval *op2);                 /* $result = $op1 % $op2 */
zend_result bitwise_or_function(zval *result, zval *op1, zval *op2);          /* $result = $op1 | $op2 */
zend_result bitwise_and_function(zval *result, zval *op1, zval *op2);         /* $result = $op1 & $op2 */
zend_result bitwise_xor_function(zval *result, zval *op1, zval *op2);         /* $result = $op1 ^ $op2 */
zend_result boolean_xor_function(zval *result, zval *op1, zval *op2);         /* $result = $op1 xor $op2 */
zend_result shift_left_function(zval *result, zval *op1, zval *op2);          /* $result = $op1 << $op2 */
zend_result shift_right_function(zval *result, zval *op1, zval *op2);         /* $result = $op1 >> $op2 */
zend_result concat_function(zval *result, zval *op1, zval *op2);              /* $result = $op1 . $op2 */

zend_result bitwise_not_function(zval *result, zval *op1);                    /* $result = ~$op1 */
zend_result boolean_not_function(zval *result, zval *op1);                    /* $result = !$op1 */

zend_result increment_function(zval *op);                                     /* ++$op */
zend_result decrement_function(zval *op);                                     /* --$op */

zend_result compare_function(zval *result, zval *op1, zval *op2);             /* $result = $op1 <=> $op2 */
zend_result is_equal_function(zval *result, zval *op1, zval *op2);            /* $result = $op1 == $op2 */
zend_result is_not_equal_function(zval *result, zval *op1, zval *op2);        /* $result = $op1 != $op2 */
zend_result is_identical_function(zval *result, zval *op1, zval *op2);        /* $result = $op1 === $op2 */
zend_result is_not_identical_function(zval *result, zval *op1, zval *op2);    /* $result = $op1 !== $op2 */
zend_result is_smaller_function(zval *result, zval *op1, zval *op2);          /* $result = $op1 < $op2 */
zend_result is_smaller_or_equal_function(zval *result, zval *op1, zval *op2); /* $result = $op1 <= $op2 */
/* $op1 > $op2 is same as $op2 < $op1 */
/* $op1 >= $op2 is same as $op2 <= $op1 */

为了进行比较,还有另外两种变体可以返回比较结果,而不是将其存储在 zval 中:

bool zend_is_identical(zval *op1, zval *op2);
int zend_compare(zval *op1, zval *op2);

zend_compare() 函数返回一个类似于 PHP 中 <=> 运算符的三向比较结果,根据 op1 是小于、等于还是大于 op2,结果分别小于、等于或大于零。

最后,还有许多以 fast_ 为前缀的变体。这些是经过优化的实现,它们将参数限制为特定类型,或者内联部分实现,和/或使用内联汇编来实现:

/* op1 must have type IS_LONG, implementation uses inline assembly. */
static zend_always_inline void fast_long_increment_function(zval *op1);
static zend_always_inline void fast_long_decrement_function(zval *op1);
/* op1 and op2 must have type IS_LONG, implementation uses inline assembly. */
static zend_always_inline void fast_long_add_function(zval *result, zval *op1, zval *op2);
static zend_always_inline void fast_long_sub_function(zval *result, zval *op1, zval *op2);
/* op1, op2 may have any type, but IS_LONG and IS_DOUBLE addition is inlined. */
static zend_always_inline zend_result fast_add_function(zval *result, zval *op1, zval *op2);
/* op1, op2 may have any type, but IS_LONG, IS_DOUBLE and IS_STRING equality is inlined. */
static zend_always_inline bool fast_equal_check_function(zval *op1, zval *op2);
/* op1 must have type IS_LONG, op2 can have any type. */
static zend_always_inline bool fast_equal_check_long(zval *op1, zval *op2);
/* op1 must have type IS_DOUBLE, op2 can have any type. */
static zend_always_inline bool fast_equal_check_string(zval *op1, zval *op2);
/* op1, op2 may have any type, but part of the implementation is inlined. */
static zend_always_inline bool fast_is_identical_function(zval *op1, zval *op2);
static zend_always_inline bool fast_is_not_identical_function(zval *op1, zval *op2);