Make WordPress Core

Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#50531 closed task (blessed) (fixed)

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

Reported by: johnbillion's profile johnbillion Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 5.8 Priority: normal
Severity: normal Version:
Component: Plugins Keywords: has-patch php8 needs-docs
Focuses: docs Cc:


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 (16)

#1 @johnbillion
4 years ago

  • Keywords has-patch added

PR here which hasn't been picked up:

#2 @jrf
4 years 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
4 years ago

Related ticket: #51553

#4 follow-up: @jrf
4 years 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
4 years ago

In 49196:

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

See #50531, #50768

#6 @SergeyBiryukov
4 years ago

  • Type changed from enhancement to task (blessed)

#7 in reply to: ↑ 4 @johnbillion
4 years 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
4 years 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.

This ticket was mentioned in Slack in #core by hellofromtonya. View the logs.

4 years ago

#10 @johnbillion
3 years ago

  • Milestone changed from 5.7 to Future Release

#11 @SergeyBiryukov
3 years ago

  • Keywords needs-refresh removed
  • Milestone changed from Future Release to 5.8

#12 @SergeyBiryukov
3 years ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from new to closed

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.

#13 @SergeyBiryukov
3 years ago

In 50811:

Docs: Further synchronize documentation for some Plugin API functions.

Follow-up to [50807].

See #50531.

This ticket was mentioned in Slack in #core by sergey. View the logs.

3 years ago

#15 @milana_cap
3 years ago

  • Keywords needs-docs added
Note: See TracTickets for help on using tickets.