PHP Manual
Prev | Chapter 31. Source Discussion | Next

# Declaring Exported Functions

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);

Expanding `INTERNAL_FUNCTION_PARAMETERS` results in the following:

    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 Table 9.1 for descriptions).

Figure 31-1. Table 9.1. Zend'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 `ELS_FETCH()`.

Prev | Home | Next
Header File Inclusions | Up | Declaration of the Zend Function Block