[wp-trac] [WordPress Trac] #37422: do_shortcode() weakens semantics

[WordPress Trac]

#37422: do_shortcode() weakens semantics
------------------------------+-----------------------------
 Reporter:  thefarlilacfield  |      Owner:
     Type:  enhancement       |     Status:  new
 Priority:  normal            |  Milestone:  Awaiting Review
Component:  General           |    Version:  trunk
 Severity:  normal            |   Keywords:
  Focuses:  docs, template    |
------------------------------+-----------------------------
 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()}}}.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/37422>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform