Standardise the terminology used for hooks, actions, and filters in documentation

[johnbillion]

The docs and parameter names in plugin API functions use inconsistent terminology when referring to hooks, actions, and filters. Hooks are referred to variously as actions, filters, or tags. Actions and filters are sometimes referred to as hooks.

Let's improve and standardise the documentation and the parameter names. This will help developers who are new to the actions and filters API.

The correct terminology is that an action or a filter refers to the callback function attached to a hook. The add_filter(), apply_filters(), and add_action() functions support this terminology, but the do_action() function is the odd one out.

That said, I know that not everyone agrees with this terminology, so it might need some further discussion.

[johnbillion]

PR here which hasn't been picked up: ​https://github.com/WordPress/wordpress-develop/pull/377

[jrf]

I'd like to recommend this ticket gets attention and a decision prior to the release of WP 5.6/PHP 8.0.

PHP 8.0 introduces ​named arguments in function calls. This means that as soon as PHP 8.0 is out, EVERY rename of a function parameter is by definition a backward-compatibility break.

And knowing the allergy within the WP community against BC-breaks, that means that this ticket either needs to be addressed now or not at all.

[jrf]

Related ticket: #51553

[jrf]

@johnbillion I've looked through the patch. While I agree with the principle of improving the consistency of the parameter names, I find the current proposal even more confusing.

To me a "filter" or "action" refers to the hook name, not to the callback function hooked into that hook.

What about calling things by what they are ? $tag becomes $hook_name and the callback function hooked into it becomes $callback or $callback_function.

What do think ?

[johnbillion]

In 49196:

Docs: Improve the docs for the globals that are used in the actions and filters API.

See #50531, #50768

[johnbillion]

Replying to jrf:

What about calling things by what they are ? $tag becomes $hook_name and the callback function hooked into it becomes $callback or $callback_function.

Sorry I missed this comment. While the terminology I proposed makes sense in my head, I can see that it's not necessarily any clearer than what we have currently. I think you're right that $hook or $hook_name combined with $callback is clearer.

I'll work on a new PR.

[desrosj]

With RC1 due out today, let's punt this to 5.7 and prioritize for the next release. As discussed over on #51553, the PHP 8 dev note accompanying WP 5.6 will be explicitly advising against making use of the named parameters feature in PHP 8 until all parameter names within the code base can be thoroughly reviewed.

[SergeyBiryukov]

In 50807:

Plugins: Standardize the terminology used for actions, filters, and callback functions.

Use $hook_name when referring to a filter or action hook name, and $callback when referring to a callback function.

This brings more consistency to parameter names in Plugin API functions.

Includes minor code layout fixes for better readability and reordering some functions in a more logical order.

Props johnbillion, jrf, SergeyBiryukov.
Fixes #50531.

[SergeyBiryukov]

In 50811:

Docs: Further synchronize documentation for some Plugin API functions.

Follow-up to [50807].

See #50531.

https://core.trac.wordpress.org/changeset/50807