WordPress.org

Make WordPress Core

Opened 5 months ago

Last modified 12 days ago

#50531 new task (blessed)

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

Reported by: johnbillion Owned by:
Milestone: 5.7 Priority: normal
Severity: normal Version:
Component: Plugins Keywords: has-patch php8 needs-refresh
Focuses: docs Cc:

Description

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.

Change History (8)

#1 @johnbillion
5 months ago

  • Keywords has-patch added

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

#2 @jrf
7 weeks ago

  • Keywords php8 2nd-opinion added
  • Milestone changed from Future Release to 5.6

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.

#3 @jrf
6 weeks ago

Related ticket: #51553

#4 follow-up: @jrf
6 weeks ago

@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 ?

#5 @johnbillion
6 weeks ago

In 49196:

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

See #50531, #50768

#6 @SergeyBiryukov
6 weeks ago

  • Type changed from enhancement to task (blessed)

#7 in reply to: ↑ 4 @johnbillion
3 weeks ago

  • Keywords needs-refresh added; 2nd-opinion removed

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.

#8 @desrosj
12 days ago

  • Milestone changed from 5.6 to 5.7

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.

Note: See TracTickets for help on using tickets.