I was updating the codex page example for action hooks, while playing around to get some reuseable functions done (originally for some Q over here @WA). But then i ran into a problem i wasn’t aware of before: After hooking into a function to modify the output of a variable, i can’t anymore decide if i want to echo the output or just return it.
The Problem: I can modify variables that i pass to a do_action hook with a callback function. Everything i modify/add with the variable is only available inside the callback function, but not after the do_action call inside the original function.
FOR YOUR PLEASURE: I reworked it to an working example, so you can just copy/paste it in some functions.php file and see/test the problem without any efforts.
Example:
Handle data function
This is the handle_data_fn. A little over documented as it should serve as a guide on how to parse and merge default with other arguments.
You can see the problem at the end of the function right after the do_action() call.
/**
* The "global" data handle function
*
* This function can serve a lot of different purposes.
* Incl. merging db values from an options entry with input arguments.
*
* Throws a fully translateable Error if no database option name was specified.
* Tells you from which file the Error was triggered and in which line you should search it.
* Also tells you the "hook_data_handle_$args['UID']" name of the action hook where the Error occured.
*
* Uses of external function calls in order of their appearance inside the function:
* @uses: isset() - @link: http://php.net/manual/en/function.isset.php
* @uses: wp_die() - @link: http://codex.wordpress.org/Function_Reference/wp_die
* @uses: printf() - @link: http://php.net/manual/en/function.printf.php
* @uses: _e() - @link: http://codex.wordpress.org/Function_Reference/_e (i18n function)
* @uses: apply_filters() - @link: http://codex.wordpress.org/Function_Reference/apply_filters
* @uses: wp_parse_args() - @link: http://codex.wordpress.org/Function_Reference/wp_parse_args
* @uses: extract() - @link: http://php.net/manual/en/function.extract.php
* @uses: get_option() - @link: http://codex.wordpress.org/Function_Reference/get_option
* @uses: do_action() - @link: http://codex.wordpress.org/Function_Reference/do_action
* @uses: return - @link: http://php.net/manual/en/function.return.php
*
* @param: (array) mixed $args | array of arguments - `$args['UID']` is always a must have
* @param: $database | true if you want to get and modify some db-option - `$args['name']` then is a must have
* @param: $output | result from the function - @internal: should not get set
*/
function handle_data_fn( $args = array() )
{
// abort if we ain't got some unique identifier as argument
if ( !isset( $args['UID']) )
return;
// Trigger Error if an option should get retrieved from the database,
// but no option name was specified
if ( !isset( $args['name'] ) )
wp_die(
printf(
_e(
'You have to specify the "name" of a db-entry as argument inside a handle_data_fn at for the action hook: %1$s.'."\n".
'Error triggered inside: file name %2$s (line number %3$s)'
)
,'some_textdomain'
)
,'hook_data_handle_'.$args['UID'].'`'
,__FILE__
,__LINE__
);
// setup default arguments
$defaults = (
array(
'UID' => null // DB/css: #id | used to identify the data inside your database - $name[$ID] - can be used as css #id too
,'name' => null // name of DB field, should be a constant when fn get's triggered - just here for completeness, not needed
,'args' => array( // $arguments the function can handle - put default arguments in here as array data
// 'classes' => null // css: .class - example
)
,'output' => ''
,'echo' => false // if you want to echo the output or just save it in a var for later modifying
)
);
// filter defaults
$defaults = apply_filters( 'filter_defaults_'.$args['UID'], $defaults );
// merge defaults with input arguments
$args = wp_parse_args( $args, $defaults );
extract( $args, EXTR_SKIP );
// in case you want to call the global function again,
// but for some reason need to modify the merged result of defaults & arguments
$args = apply_filters( 'filter_args_'.$args['UID'], $args );
// retrieve the database option
if ( isset( $args['name'] ) )
$options = get_option( $args['name'] );
# >>> start building $output
// if true, echo the $output
if ( isset( $args['echo'] ) )
{
if ( $args['echo'] === true )
{
// do stuff here - your argument is the initial array
do_action( 'hook_data_handle_'.$args['UID'], $args, $options );
// Test output inside handle_fn:
echo '<pre>From inside handle_fn: ';
print_r($args);
echo '</pre>';
return;
}
}
// else just return the $output
// HOW CAN I NOT ECHO THE DATA HERE.
// STORING THE do_action return VALUE DOESN'T WORK.
// NEITHER DOES JUST returnING IT INSIDE THE CALLBACK FN 'modify_args_fn' BELOW
do_action( 'hook_data_handle_'.$args['UID'], $args, $options );
return;
# <<< end building $output
}
Callback functions
Those are used to a) build the initial array and b) modify the output.
/**
* EXAMPLE for how to add initial data to the handle_data_fn function.
*
* @param (array) mixed $args
*/
function build_args_fn ( $args ) {
// build initial array
$args = array(
'UID' => 'whatever_UID'
,'name' => 'some_options_name'
,'args' => array(
'class' => 'example-wrap'
)
,'echo' => true
);
handle_data_fn( $args );
}
// 'some_hook' is some hook in a template file where the output should get echoed.
add_action( 'some_hook', 'build_args_fn', 0, 1 );
/**
* EXAMPLE for how to add content and modify the options from the DB inside a handle_data_fn function.
*
* @param (array) mixed $args
* @param (array) mixed $options | db-options retrieved inside the oxo_parse function
*/
function modify_args_fn ( $args, $options )
{
$args['output'] .= '<div class="container">';
$args['output'] .= '<div class="'.$args['args']['class'].'">';
$args['output'] .= $options;
$args['output'] .= '</div>';
$args['output'] .= '</div>';
// Test output inside callback fn
echo '<pre>From inside callback: ';
print_r($args);
echo '</pre>';
// HERE'S THE PROBLEM. I CAN'T SIMPLE return IT, BECAUSE IT WOULDN'T BE AVAILABLE INSIDE MY 'data_handle_fn'.
# return $args['output'];
// I HAVE TO PRINT IT TO GET SOME OUTPUT. THE $args['output'] IS NOT AVAILABLE INSIDE THE 'handle_data_fn' AFTER THE do_action CALL.
return print $args['output'];
}
// Name of the hook comes from 'UID' argument in 'build_args_fn' combined with 'hook_data_handle_'
add_action ( 'hook_data_handle_whatever_UID', 'modify_args_fn', 10, 2 );
Thanks for any info & help about this issue.
1 Answer
If you want to return the data, the best solution is to use apply_filters() and instruct the callback to always return:
$output = apply_filters( 'hook_data_handle_'.$args['UID'], $args, $options );
if ( $args['echo'] )
echo $output;
else
return $output;
A less elegant solution would be to use output buffering.