How to deprecate a function in your WordPress plugin or theme properly

If you’re developing a WordPress plugin and fortunately your product is popular enough to improve it regularly, one thing that you would need is to replace a function with a newer version or remove it completely because it has become obsolete or deprecated.

This may be important if the changing function is something the users may use in some ways in their code. For example, a template tag with an outdated prefix like cposter_my_template_tag() is a good candidate. So we’ve decided to update it to something more unique like codeposter_my_template_tag() and we are worried about those users who are using the first version in their products. So what is the solution?

In this case, we should somehow inform the users that the mentioned function is a Deprecated one, and will be removed in next major release and users most avoid using it anymore to be safe for the future updates. It is usually done by showing a warning to anyone using the method or function.

A good example for such situations is WordPress itself. WordPress has a file where it keeps the deprecated functions for backward compatibility. You can find a couple of deprecated ones there:

wp-includes/deprecated.php

WordPress has decided to deprecated permalink_link() from version 1.2.0, and offered the_permalink() instead.

Introducing _deprecated_function()

As you saw in the WordPress example, deprecating a function is done by a native WordPress function which is _deprecated_function(). This function will raise the warning we are looking for. We can find its definition at /wp-includes/functions.php.

Use the function at the top of your deprecated function body in order to make it as deprecated and inform when it has been used.

The first parameter is the function that was called and we’re going to mark it as deprecated. You should pass the called function name as the first parameter either by typing or using the PHP magical constant __FUNCTION__.

The second parameter is used to clarify in which version of your plugin/theme the function has been deprecated. And the last one (optional) is the replacement function which should have been called instead of the deprecated.

Note that these three parameters are only used for making a proper warning message and don’t do anything except triggering a PHP error, so don’t forget to call the replacement function inside the body yourself.

Deprecate a file

Another interesting function that you may use during your development is _deprecated_file() which is used to mark a file deprecated and inform when it has been used.

For example, /wp-admin/upgrade-functions.php is an old file and must not be included. If you take a look at its source code, you can find out how WordPress has deprecated this file from version 2.5.0.

Deprecate an argument

As we did for functions and files, we could mark a function argument as deprecated too. Sometimes we want to adjust one of our functions by removing an argument ( for example ) which is not needed anymore. To let the users know about the change, we can make a warning message regarding our adjustment using _deprecated_arguement() function.

The definition and parameters are similar to the previous ones, but the difference is just the way we use it. As an example, the_author() function used to accept two parameters but now both are deprecated. As you see below, we need to check whether the deprecated argument is used and respond properly by a simple if statement.

_doing_it_wrong()

Occasionally you’re not deprecating a function but need to inform users about a wrong usage of a function as it may have bad side effects on their theme or plugin.

The example below is from WooCommerce source code which prevents theme/plugin developers from calling wc_get_order() before woocommerce_init action.

Conclusion

In this article, we have taken a look at four WordPress functions that we can use to approach depreciation in our plugins or themes. Mistakes and improvements are part of the development and usually, we need to let go of old code and introduce new versions as we go further. So we need a mechanism to cover it smartly. Fortunately, WordPress has got all we need to fix and improve things properly.

 

Leave a Reply

Your email address will not be published. Required fields are marked *