Functionality: Automatic linking for hooks (filters/actions)

[Aternus]

Overview: Add ability to reference the correct hook by using a shortcode.

Workflow:

1. User adds [filter name="the_title"] or [action name="do_shortcode"]
2. The system will look for a hook name in the reference database
3. If successful, a link will be created to the reference
4. If not successful, the name of the filter will be displayed with a red underline (marking missing content)

Implementation: Should be pretty straight forward.

What do you think? Improvements?

[ramiy]

It should be an enclosing shortcode [filter name="the_title"]content[/filter] to allow you to change the text in the link.

Very simple to implement.

[ramiy]

Quick code example: https://generatewp.com/snippet/XBJ1Y7Q/

[Clorith]

I'm not sure a shortcode is needed here, the post editor has a link button which does exactly the same, and with many of the hooks and actions in core that may use variables as part of the trigger, the shortcode would fail for them in general.

Better to build up a good pattern of adding links with the editor then having to switch between the two.

[Kenshino]

@Clorith DevHub and Helphub won't on the same installation though. How would the editor's link function work then?

Or are you talking about doing it manually?

[Clorith]

I mean doing it manually, that's the only way you'll get a reliable link to the docs you want

[Aternus]

Do we have a stable link structure? What will happen if the link structure changes?

While I can see the benefit of doing it manually there is also the downside of doing 3 extra steps each time you want to create a link for a hook. I admit, I'm lazy, but I prefer letting the shortcode solve this issues instead of forcing myself to do this every single time.

[Clorith]

I just have concerns when it comes to the variable stuff, would people remember in documentation that admin_post_plugin-does-magical-stuff needs to be linked to https://developer.wordpress.org/reference/hooks/admin_post_action/ as the hook is variable (and would they know the variable LINK in use without looking it up any way)..

I don't think the URLs changing is something we need to worry about, they are being directly linked in core doc blocks for reference, they're pretty set at this point (Just thinking of possible caveats to the approach so that we don't have a stumble there :) ).

There's also the awkward moment of a typo in a hook name, and we auto-link it to the wrong hook, things like this to consider, we could verify pages exist by getting the head, but we'd not want to do that on every shortcode call.

[Aternus]

If I'm understanding you correctly, we need a way to verify the integrity of the link and notify the author if it is broken.

This can be done by limiting scope of the call to is_admin() and displaying it on the front end with a red underline (similar to what we currently have in Codex).

This will also ensure that all links are validated when someone looks at a page.

What about adding a transient that has a 48 hour life-span that will prevent unnecessary calls?

A totally different approach would be to use "Broken Links Checker" for this functionality and ignore it completely inside the shortcode.

This is a draft. Feedback is welcome!

[Kenshino]

I can see this of really helping in a way that -

If I type get_template_part(), it'd auto link without using any shortcode.

See DevHub's implementation at https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/formatting.php#L164

[moorscode]

Dynamic hooks/filters For dynamic hook names, splitting on _ and - and walking back cutting off the last item until a hook is found would be a fairly reliable method to determine the base hook.

Name lookup This would only be realistic if there is an API to query hook names against in a fast and efficient way. Is there an API available to validate hook names against? Are there any hooks and filters which don't have a documentation page; thus marking the link as invalid as it should be and the location is where it should be?

Performance Independent to the implementation there should be a cache layer in between using transients to keep page loads in check.

oEmbed Considering other methods of implementing data from sources on a page, oEmbed comes to mind. I guess the dynamic part would be pretty hacky to force it in the intended oEmbed way, so it does not really seem like a good alternative. Though I wanted to mention it for consideration.