Make WordPress Core

Opened 23 months ago

Closed 8 months ago

#54871 closed enhancement (invalid)

Specify which params are required in add_shortcode callback

Reported by: mkarimzada's profile mkarimzada Owned by:
Milestone: Priority: normal
Severity: trivial Version: 5.8.3
Component: Shortcodes Keywords: php80 close
Focuses: docs Cc:


Looking at the source code, it's not clear which parameters are required for add_shortcode $callback function.

If you have any functions/methods that have required parameters after optional parameters, you will get a deprecation notice in PHP 8.

Required parameter $shortcode_tag follows optional parameter $content

The deprecation does not apply if there are types declared on the optional parameters, and the default values are null.

Change History (3)

#1 @costdev
23 months ago

  • Keywords php8 added

#2 @jrf
23 months ago

  • Keywords close added; needs-dev-note needs-codex needs-docs removed

@mkarimzada Thanks for opening this ticket.

I must be missing something, but as far as I can see the docblock specifies exactly which parameters are expected and in which order on the lines just below the one you linked:

Every shortcode callback is passed three parameters by default,
including an array of attributes ($atts), the shortcode content
or null if not set ($content), and finally the shortcode tag
itself ($shortcode_tag), in that order.

When I read that, I come to a function signature of:

function my_shortcode_callback($atts = array(), $content = null, $short_tag = '') {}

// Or in typed form:
function my_shortcode_callback(array $atts = array(), ?string $content = null, string $short_tag = '') {}

The first two parameters are "optional" as the shortcode when used:

  • may not be passed any attributes [my_shortcode]content[/my_shortcode]
  • may not be passed any content [my_shortcode att="value" /]

The third parameter is optional as, if the callback function is used only for that one shortcode, it won't be needed in the callback function itself.

WordPress will always pass all three parameters, but the callback function definition can leave off the third, the second and third or even all parameters.

Note: PHP 8.0 named parameters are not supported, so these parameters are passed positionally.

So what is the enhancement you expect here ?

#3 @hellofromTonya
8 months ago

  • Keywords php80 added; php8 removed
  • Milestone Awaiting Review deleted
  • Resolution set to invalid
  • Status changed from new to closed

Hello @mkarimzada,

it's not clear which parameters are required for add_shortcode $callback function.

As @jrf noted, the function's docblock provides you with that information and there's more information available in the Developer Resources.

I've closed this ticket. Why? It's been a close candidate for 15 months with no additional follow-up. The docs and resources do clearly identify that "Every shortcode callback is passed three parameters by default" and what those parameters are.

However, please reopen if there is more to consider that could help to further clarify documentation needs.

Note: See TracTickets for help on using tickets.