Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

I am having trouble wrapping my head around these two functions. I understand do_action() but I don't see clearly when do_action_ref_array() would be useful. Couldn't we pass an array to do_action() as well?

share|improve this question

1 Answer 1

up vote 5 down vote accepted
  • If you pass an array to do_action_ref_array(), each element’s value of that array will be passed as a separate parameter to the callback. The keys are lost.

  • If you pass an array to do_action(), the complete array will be passed as one single parameter to the callback. The keys stay intact.

Let’s look at the differences between do_action() and do_action_ref_array() in a simple plugin:

add_action( 'wp_footer',             'action_diff_test' );
add_action( 'diff_action',           'diff_test_callback', 10, 999 );
add_action( 'diff_action_ref_array', 'diff_test_callback', 10, 999 );

/**
 * call test actions
 */
function action_diff_test()
{
    $args = array (
        'foo'   => 'bar',
        'hello' => 'world',
        0       => 123
    );

    do_action(           'diff_action',           $args );
    do_action_ref_array( 'diff_action_ref_array', $args );
}
/**
 * callback for test actions
 */
function diff_test_callback()
{
    $args = func_get_args();
    print current_filter() . ', ' . func_num_args() . ' arguments';
    ?>
    <pre><?php
    print htmlspecialchars(
        print_r( $args, TRUE ),
        ENT_QUOTES,
        'utf-8',
        FALSE
    );
    ?></pre>
    <?php
}

Result:

diff_action, 1 arguments 
Array
(
    [0] => Array
        (
            [foo] => bar
            [hello] => world
            [0] => 123
        )

)

diff_action_ref_array, 3 arguments 
Array
(
    [0] => bar
    [1] => world
    [2] => 123
)

do_action_ref_array() was introduced 2006 to handle parameters passed by reference better in PHP 4. A review of the function 2011 was closed as wontfix. But the conclusion was not to use for new functions in WordPress anymore, because in PHP 5 you can do that with do_action() too. The problem from 2006 is not a problem nowadays.

Do not use do_action_ref_array() in your custom hooks, but learn how to read it.

share|improve this answer
    
Excellent explanation, thanks! –  drtanz Mar 13 '13 at 13:22

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.