The return value of the PHP function

return value

The user space function uses the return keyword to return information to its calling space, which is the same as the C language syntax.

For example:

function Sample_long () {return  
  ;  
}  
$bar = Sample_long ();

When Sample_long () is invoked, returns 42 and sets it to the $bar variable. The equivalent code in the C language is as follows:

int Sample_long (void) {return  
  ;  
}  
void Main (void) {  
  int bar = Sample_long ();  
}

Of course, in the C language you always know what the called function is and return it based on the function prototype, so you define the variable that returns the result store. When processing PHP user space, variable types are dynamic and depend instead on the type of Zval described in Chapter 2nd "in and out of variables."

Return_value variable

You might think that your internal function should return directly to a zval, or allocate a zval memory space and return Zval * as follows.

Php_function (Sample_long_wrong)  
{  
    zval *retval;  
      
    Make_std_zval (retval);  
    Zval_long (retval,);  
      
    return retval;  
}

Unfortunately, this is not the right thing to do. Not to force each function implementation to assign Zval and return it. Instead, the Zend engine allocates this space in advance of the function call. The Zval type is then initialized to Is_null and the value is passed as the parameter name Return_value. The following is the right approach:

Php_function (Sample_long)  
{  
    Zval_long (return_value,);  
    return;  
}

Note that the php_function () implementation does not return any values directly. Instead, the appropriate data is ejected directly into the Return_value parameter, and the Zend engine processes it after the internal function execution completes.

Tip: The Zval_long () macro is an encapsulation of multiple assignment operations:

Z_type_p (return_value) = Is_long;  
Z_lval_p (Return_value) = 42;

or more directly:

Return_value->type = Is_long;  
Return_value->value.lval = 42;

The Is_ref and RefCount properties of return_value should not be directly modified by internal functions. These values are initialized and processed by the Zend engine when calling your function.

Now let's take a look at this particular function and add it to the sample extension created in Chapter 5th, "Your first extension." Just add the function under the Sample_hello_world () function and add Sample_long () to the php_sample_functions structure:

Static Function_entry php_sample_functions[] = {  
    Php_fe (sample_hello_world, NULL)  
    Php_fe (Sample_long, NULL )  
    {null, NULL, NULL}  
};

Now we can perform the make rebuild extension.

If all OK, you can run PHP and test the new function:

$ Php-r ' Var_dump (Sample_long ());

Wrap a more compact macro

There is a duplicate part of the zval_* () macro in terms of code readability and maintainability: Return_value variables. In this case, replace the zval of the macro with retval, and we can omit the return_value at the time of the call.

In the previous example, the implementation code for Sample_long () can be reduced to the following:

Php_function (Sample_long)  
{  
    retval_long ();  
    return;  
}