To declare functions that are to be exported (i.e.,
made available to PHP as new native functions), Zend provides a
set of macros. A sample declaration looks like this:
ZEND_FUNCTION ( my_function ); |
ZEND_FUNCTION
declares a new C function that complies with Zend's internal
API. This means that the function is of type
void
and accepts
INTERNAL_FUNCTION_PARAMETERS
(another macro) as parameters. Additionally, it prefixes the
function name with
zif
. The immediately expanded version of the above definitions
would look like this:
void zif_my_function ( INTERNAL_FUNCTION_PARAMETERS ); |
void zif_my_function( int ht , zval * return_value , zval * this_ptr , int return_value_used , zend_executor_globals * executor_globals ); |
Since the interpreter and executor core have been
separated from the main PHP package, a second API defining
macros and function sets has evolved: the Zend API. As the Zend
API now handles quite a few of the responsibilities that
previously belonged to PHP, a lot of PHP functions have been
reduced to macros aliasing to calls into the Zend API. The
recommended practice is to use the Zend API wherever possible,
as the old API is only preserved for compatibility reasons. For
example, the types
zval
and
pval
are identical.
zval
is Zend's definition;
pval
is PHP's definition (actually,
pval
is an alias for
zval
now). As the macro
INTERNAL_FUNCTION_PARAMETERS
is a Zend macro, the above declaration contains
zval
. When writing code, you should always use
zval
to conform to the new Zend API.
The parameter list of this declaration is very
important; you should keep these parameters in mind (see
表31-1
for descriptions).
表 31-1Zend's Parameters to Functions Called from PHP
Parameter | Description |
ht | The number of arguments passed to the Zend function. You should not touch this directly, but instead use ZEND_NUM_ARGS() to obtain the value. |
return_value | This variable is used to pass any return values of your function back to PHP. Access to this variable is best done using the predefined macros. For a description of these see below. |
this_ptr | Using this variable, you can gain access to the object in which your function is contained, if it's used within an object. Use the function getThis() to obtain this pointer. |
return_value_used | This flag indicates whether an eventual return value from this function will actually be used by the calling script. 0 indicates that the return value is not used; 1 indicates that the caller expects a return value. Evaluation of this flag can be done to verify correct usage of the function as well as speed optimizations in case returning a value requires expensive operations (for an example, see how array.c makes use of this). |
executor_globals | This variable points to global settings of the Zend engine. You'll find this useful when creating new variables, for example (more about this later). The executor globals can also be introduced to your function by using the macro TSRMLS_FETCH() . |