WordPress.org

Make WordPress Core

Opened 15 months ago

Closed 5 months ago

Last modified 8 weeks ago

#50531 closed task (blessed) (fixed)

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

Reported by: johnbillion Owned by: SergeyBiryukov
Milestone: 5.8 Priority: normal
Severity: normal Version:
Component: Plugins Keywords: has-patch php8 needs-docs
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 (16)

#1 @johnbillion
15 months ago

  • Keywords has-patch added

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

#2 @jrf
11 months 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
11 months ago

Related ticket: #51553

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

In 49196:

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

See #50531, #50768

#6 @SergeyBiryukov
11 months ago

  • Type changed from enhancement to task (blessed)

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


9 months ago

#10 @johnbillion
8 months ago

  • Milestone changed from 5.7 to Future Release

#11 @SergeyBiryukov
5 months ago

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

#12 @SergeyBiryukov
5 months 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
5 months 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.


5 months ago

#15 @milana_cap
4 months ago

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