Specify which params are required in add_shortcode callback

[mkarimzada]

Looking at the source code
​https://github.com/WordPress/wordpress-develop/blob/ba943e113d3b31b121f77a2d30aebe14b047c69d/src/wp-includes/shortcodes.php#L57, 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. ​https://bugs.php.net/bug.php?id=53399

[jrf]

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

​https://github.com/WordPress/wordpress-develop/blob/ba943e113d3b31b121f77a2d30aebe14b047c69d/src/wp-includes/shortcodes.php#L58-L61

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

<?php
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 ?

[hellofromTonya]

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.