do_shortcode() weakens semantics

[thefarlilacfield]

This report / enhancement request is regarding a matter that has no critical impact on the use or performance of WordPress. Dealing with it should be deferred to a time in which future WordPress semantics are being discussed.

This report / enhancement request is based on developer (user) experience encountering the do_shortcode() function for the first time. Because of the normal semantics used in templates (i.e. the_content() vs get_the_content()) it was expected that this function would output to the current buffer rather than return a string.

A cursory examination of do_ prefixed functions to establish whether there was a different frame of reference in which the function name arose produced no definite result; it was found that do_feed_rdf() caused the direct inclusion of a template that echoed content to a buffer.

The logic of the do_ prefix is evident in that it attempts to indicate that this is the point at which the shortcode is evaluated in the way that do_action() evaluates the callbacks queued at an action hook. This makes sense insofar as the function cannot guarantee that there will be no side-effects arising from the evaluation of developer (user) shortcodes. However, the semantics of 'do' suggest that the code will positively act with relation to the external world. apply_filter() is no better able to guarantee the absence of side-effects, but it avoids suggesting either that it is a getter function, or that side-effects should be an expected result.

A reference search produced few results, suggesting that apply_ is not a well-defined concept within the WordPress corpus. However, it is notable in that it attempts to evoke the difference between an action and a filter. An action is done; a filter takes a string and applies a function to it. These words reinforce the notion that something which is done is completed, and can be released from the mind as an ongoing, whereas something which is applied must be in relation to another thing, which remains after the application is performed.

I would therefore suggest as a long-term enhancement the depreciation of do_shortcode() in favour of the identical function apply_shortcode().

[pento]

Thank you for this suggestion, @thefarlilacfield!

I tend to agree with how you've defined do_ vs apply_. I'd probably use apply_shortcodes() (plural), though, the same as apply_filters(), because multiple shortcodes will be applied.

[SergeyBiryukov]

A precedent of introducing an alias: #24164

[DrewAPicture]

Assigning ownership to mark the good-first-bug as "claimed".

[SergeyBiryukov]

Just noting the current patch is reversed (replacing non-existing code with existing code), so needs a refresh.

[SergeyBiryukov]

Introducing an apply_shortcodes() alias for do_shortcode() for better semantics in the same way [27409] did for get_the_permalink()/get_permalink() makes sense to me.

Deprecating do_shortcode() is probably not an option due to high usage numbers in plugins and themes, however having an alias could also be a first step towards its eventual deprecation if there is consensus it's worth the effort.

[SergeyBiryukov]

In 47004:

Shortcodes: Introduce apply_shortcodes() as an alias for do_shortcode().

This better aligns with the semantics of applying filters to the input and returning a result, rather than performing an action and outputting to the current buffer.

Props ljasinskipl, thefarlilacfield.
Fixes #37422.

[audrasjb]

Dev note published: ​https://make.wordpress.org/core/2020/02/13/wordpress-5-4-introduces-apply-shortcodes-as-an-alias-for-do-shortcode/