WordPress: apply_shortcodes vs do_shortcode

WordPress 5.4 was released on March 31, 2020. This version introduced a new function for outputting shortcode content, the apply_shortcodes() function.

This function is nothing more than an alias for the do_shortcode() function. This method’s description in the WordPress Code Reference library like:

Search content for shortcodes and filter shortcodes through their hooks.


and the function’s signature is pretty simple:

do_shortcode( string $content, bool $ignore_html = false )

Looking at it in more detail, we can see that it does a very simple thing. It takes the $content, parses it, and applies the correct filters to the matched shortcodes and returns the result.

If you need help with better understanding what a shortcode is, here is an article related to Creating WordPress Shortcodes.

Since apply_shortcodes is only an alias of this function it needs no other details. Here you can see the function like it is in the codebase as of WP 5.5:

Why was apply_shortcodes() introduced?

According to Jb Audras’s post on the Make WordPress Core Blog the idea behind it was fixing a semantics issue. In WordPress, the semantics of the do_* functions mean that the respective function would display the result. However, do_shortcode() only returns the result. So, the result needs to be echoed to be displayed.

Furthermore, the do_shortcode() function filters ALL the shortcodes that are found within the $content that is passed to it and not just one of them as the singular of shortcode suggests. So, this would be a second semantics issue which was not mentioned in the article linked above.

This is how apply_shortcodes() was born. It fixes both semantics issues. Its name clearly mentions that it applies the filters on the found shortcodes. In this case, the code needed to apply and output the filtered content would be:

echo apply_shortcodes( '[my_shortcode]My Text[/my_shortcode]' );

Switching do_shortcode to apply_shortcodes

In the same blog post, Jb Audras mentioned that due to the amount of themes and plugins using the do_shortcode() function there is no plan for deprecating it in the near future. However, if the developers start migrating to the new and much more semantic apply_shortcodes() function, the core team can plan to deprecate the old one.

Themes/Plugins authors and WordPress developers are invited to start using apply_shortcodes() instead of do_shortcode().


With WordPress 5.4, apply_shortcodes() is now the recommended way to display the result of a shortcode.

It seems that even the WordPress Core team still needs to migrate towards the new function since there are at least 4 do_shortcode() uses in the WordPress Core codebase as of WP 5.5.

Final mentions

Even though there are many semantics issues in the WordPress codebase, the apply_shortcodes function seems to be a step in the good direction when it comes to bringing WordPress core codebase towards being better from a semantics point of view.

I am looking forward to more changes like this one.

Thank you for reading this post. Let me know in the comments below what is your opinion on this kind of changes.

Leave a Comment