PHP: Calling User Functions - Manual

downloads | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | conferences | my php.net

search for in the

Initialization File Support Startup and Shutdown Functions

Last updated: Fri, 26 Jan 2007

view this page in

# Calling User Functions

You can call user functions from your own modules, which is very handy when implementing callbacks; for example, for array walking, searching, or simply for event-based programs.

User functions can be called with the function call_user_function_ex(). It requires a hash value for the function table you want to access, a pointer to an object (if you want to call a method), the function name, return value, number of arguments, argument array, and a flag indicating whether you want to perform zval separation.

    ZEND_API int call_user_function_ex(HashTable *function_table, zval *object,
    zval *function_name, zval **retval_ptr_ptr,
    int param_count, zval **params[],
    int no_separation);

Note that you don't have to specify both `function_table` and `object`; either will do. If you want to call a method, you have to supply the object that contains this method, in which case call_user_function()automatically sets the function table to this object's function table. Otherwise, you only need to specify `function_table` and can set `object` to `NULL`.

Usually, the default function table is the "root" function table containing all function entries. This function table is part of the compiler globals and can be accessed using the macro `CG`. To introduce the compiler globals to your function, call the macro `TSRMLS_FETCH` once.

The function name is specified in a `zval` container. This might be a bit surprising at first, but is quite a logical step, since most of the time you'll accept function names as parameters from calling functions within your script, which in turn are contained in `zval` containers again. Thus, you only have to pass your arguments through to this function. This `zval` must be of type `IS_STRING`.

The next argument consists of a pointer to the return value. You don't have to allocate memory for this container; the function will do so by itself. However, you have to destroy this container (using zval_dtor()) afterward!

Next is the parameter count as integer and an array containing all necessary parameters. The last argument specifies whether the function should perform zval separation - this should always be set to `0`. If set to `1`, the function consumes less memory but fails if any of the parameters need separation.

Прим. 46-15 shows a small demonstration of calling a user function. The code calls a function that's supplied to it as argument and directly passes this function's return value through as its own return value. Note the use of the constructor and destructor calls at the end - it might not be necessary to do it this way here (since they should be separate values, the assignment might be safe), but this is bulletproof.

Пример 46-15. Calling user functions.

    zval **function_name;
    zval *retval;

    if((ZEND_NUM_ARGS() != 1) || (zend_get_parameters_ex(1, &function_name) != SUCCESS))
    {
        WRONG_PARAM_COUNT;
    }

    if((*function_name)->type != IS_STRING)
    {
        zend_error(E_ERROR, "Function requires string argument");
    }

    TSRMSLS_FETCH();

    if(call_user_function_ex(CG(function_table), NULL, *function_name, &retval, 0, NULL, 0) != SUCCESS)
    {
        zend_error(E_ERROR, "Function call failed");
    }

    zend_printf("We have %i as type\n", retval->type);

    *return_value = *retval;
    zval_copy_ctor(return_value);
    zval_ptr_dtor(&retval);

    <?php

    dl("call_userland.so");

    function test_function()
    {
        echo "We are in the test function!\n";
        return 'hello';
    }

    $return_value = call_userland("test_function");

    echo "Return value: '$return_value'";
    ?>

Результат выполнения данного примера:

We are in the test function! We have 3 as type Return value: 'hello'

add a note User Contributed Notes
Calling User Functions
leon at antrophia dot com
25-Dec-2002 11:53
`This description is a bit outdated. I don't know since when, but I am using PHP 4.2.3 and an argument has been added.
I have used this and this works (and take special note to the last argument) :
call_user_function_ex(CG(function_table), NULL, function_name, &return, 1, array, 0, NULL TSRMLS_CC) == FAILURE
Hope this helps. Took me one news post on php.dev to find out ;)`
k at ailis dot de
28-Mar-2002 05:43
`An information that is missing here: The function name parameter can be an array with two elements. The first element is an object reference or a class name and the second element is the method name. Zend recognizes if the parameter is a string (which results in a normal function call or a normal method call if the object parameter is used) or if it is an array.`
add a note
Initialization File Support Startup and Shutdown Functions

Last updated: Fri, 26 Jan 2007
show source | credits | stats | sitemap | contact | advertising | mirror sites
Copyright © 2001-2007 The PHP Group
All rights reserved.
This mirror generously provided by: Yahoo! Inc.
Last updated: Sat Mar 10 10:36:09 2007 PST