WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 9 months ago

Last modified 8 months ago

#37422 closed enhancement (fixed)

do_shortcode() weakens semantics

Reported by: thefarlilacfield Owned by: ljasinskipl
Milestone: 5.4 Priority: normal
Severity: normal Version:
Component: Shortcodes Keywords: good-first-bug has-patch needs-refresh has-dev-note
Focuses: docs, template Cc:

Description

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 4 years ago.

Download all attachments as: .zip

Change History (13)

#1 @SergeyBiryukov
4 years ago

  • Component changed from General to Shortcodes

#2 @pento
4 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
4 years ago

A precedent of introducing an alias: #24164

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

@ljasinskipl
4 years ago

#4 @ljasinskipl
4 years ago

  • Keywords has-patch added; needs-patch removed

#5 @DrewAPicture
3 years ago

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

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

This ticket was mentioned in Slack in #core by sergey. View the logs.


10 months ago

#7 @SergeyBiryukov
10 months ago

  • Keywords needs-refresh added
  • Milestone changed from Future Release to 5.4

#8 @SergeyBiryukov
10 months ago

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

#9 @SergeyBiryukov
9 months ago

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

Version 0, edited 9 months ago by SergeyBiryukov (next)

#10 @SergeyBiryukov
9 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#11 @audrasjb
8 months ago

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