do_action_ref_array()

I’m going to assume you want to hook this action, as opposed to initiating an action in your code for someone else to hook.

You still hook this with add_action() where the $tag argument is just a label identifying an action, the same way as do_action() does.

The ref_array variant is useful for passing a bunch of parameters. All the parameters are stuffed into an array, instead of listing each one. So instead of

do_action('sample',$1,$2,$3,$4,$5);
add_action('sample', 'my_handler', 10, 5);
function my_handler($1,$2,$3,$4,$5) {
  //do stuff with 5 parms
  return $1;
}

we can just do

$arg = array (1,2,3,4,5);
do_action_ref_array('sample',$arg);
add_action('sample', 'my_handler');
function my_handler($five_parms) {
  //do stuff with 5 array elements
  return $five_parms;
}

It’s up to you to do something with the array elements, or not. It’s rare to use all of them, but it’s nice to have a selection to call on depending on the situation. In addition, the whole array can be returned, no matter what was changed. Instead of just returning the first argument.

Thank you! That makes a LOT more sense. People like you should write the bloody guides! Apologies for the late reply…

Well, I don’t see much benefit with the ref_array except or the last part – returning it as a whole instead of individual arguments.