Make WordPress Core

Opened 3 years ago

Last modified 2 years ago

#37422 assigned enhancement

do_shortcode() weakens semantics

Reported by: thefarlilacfield Owned by: ljasinskipl
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Shortcodes Keywords: good-first-bug has-patch
Focuses: docs, template Cc:
PR Number:


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

Attachments (1)

37422.patch (5.5 KB) - added by ljasinskipl 3 years ago.

Download all attachments as: .zip

Change History (6)

#1 @SergeyBiryukov
3 years ago

  • Component changed from General to Shortcodes

#2 @pento
3 years ago

  • Keywords needs-patch good-first-bug added
  • Milestone changed from Awaiting Review to Future Release
  • Version trunk deleted

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.

#3 @SergeyBiryukov
3 years ago

A precedent of introducing an alias: #24164

Last edited 3 years ago by SergeyBiryukov (previous) (diff)

3 years ago

#4 @ljasinskipl
3 years ago

  • Keywords has-patch added; needs-patch removed

#5 @DrewAPicture
2 years ago

  • Owner set to ljasinskipl
  • Status changed from new to assigned

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

Note: See TracTickets for help on using tickets.