Dynamic Hooks Naming Convention

[ramiy]

Currently, WordPress core has no naming-convention for ​dynamic hooks. I'm talking about actions and filters which have parameters in their name.

Proposed Change

Dynamic hooks like:

do_action( 'wp_hook_' . $dynamic_field . '_name' );

Should be replaced with:

do_action( "wp_hook_{$dynamic_field}_name" );

New Naming Convention

Currently, we use both ways to concatenate dynamic fields. We need to have a single standard way to do that.

When hook names have dynamic fields, we should use "wp_hook_{$dynamic_field}_name". It's more readable structure for developers and has ​performance benefits with multiple dynamic fields, as PHP is forced to re-concatenate with every '.' operator.

[peterwilsoncc]

Current practice is for WordPress to avoid refactoring code for such cases as it makes it more difficult to see the history of the project.

Dynamically named hooks are also a thing of the past because they make searching more difficult for developers, as you say.

For these reasons I'll close this wontfix.

[ramiy]

@peterwilsoncc Not sure why you closed the ticket - the hook name is not changing.

Currently, hooks that use 'wp_hook_' . $dynamic_field . '_name' structure are already presented as "wp_hook_{$dynamic_field}_name" in the ​code reference.

The change won't affect the history. And won't affect the search in the code reference. the ​WordPress-phpDoc-Parse has a very smart script, it converts dynamic hooks artificially (see this hook in ​code reference). Applying the patch won't affect the code reference and the search.

Besides, it has performance benefits and it sets a new conventions. Those are good things.

Can we at least discuss about the proposal before closing the ticket? I will love to hear @DrewAPicture opinion, and the docs team, about the change.

[DrewAPicture]

Replying to peterwilsoncc:

Current practice is for WordPress to avoid refactoring code for such cases as it makes it more difficult to see the history of the project.

I actually think there's merit in ignoring the refactoring rule in this instance. Standardizing on interpolation or concatenation would be a good step toward improving these hooks' ability to self document.

Typically, concatenation is going to be faster unless there's multiple parts, at which point the performance gain is largely negated by full concatenations happening for each successive part.

Personally, I prefer interpolation simply because it's easier to read linearly, and we're all about self-documenting code here.

As for whether they're a thing of the past, we introduced four new dynamic hooks in 4.6 alone ;)

Dynamically named hooks are also a thing of the past because they make searching more difficult for developers, as you say.

I think with the introduction of dynamic hook aliases (probably in 4.7, if I can get my act together) will help a lot with search.

[DrewAPicture]

​Hook aliases spreadsheet I started a year ago, for anyone interested.

The spreadsheet is a little out of date for new hooks added in the last year, but the gist is to document common aliases of dynamic hooks right in the DocBlocks (and therefore in the Code Reference).

So searching for publish_post in core would actually point you to {$new_status}_{$post->post_type} hook doc. If searching it on the Code Reference, you'd be taken to the ​corresponding reference page.

I should probably write a post on make/docs to get this started. No time like the present!

[ramiy]

Replying to DrewAPicture:

​Hook aliases spreadsheet I started a year ago.

The spreadsheet has 118 hooks listed. The code reference say's we have ​280 dynamic hooks.

No time like the present!

Lets do it in 4.7, I can help.

[DrewAPicture]

In 38307:

Hooks: Standardize naming of dynamic hooks to use interpolation vs concatenation.

Benefits gained in discoverability and self-documentation throughout core trump the negligible performance hit in using interpolation in hook names.

Props ramiy.
See #37748.

[johnbillion]

I approve of this change.

[DrewAPicture]

Added a ​Interpolation for Naming Dynamic Hooks section to the Core Coding Standards.