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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
/** * Deprecated functions from past WordPress versions. You shouldn't use these * functions and look for the alternatives instead. The functions will be * removed in a later version. * * @package WordPress * @subpackage Deprecated */ /* * Deprecated functions come here to die. */ /** * Print the permalink of the current post in the loop. * * @since 0.71 * @deprecated 1.2.0 Use the_permalink() * @see the_permalink() */ function permalink_link() { _deprecated_function( __FUNCTION__, '1.2.0', 'the_permalink()' ); the_permalink(); } |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?php /** * WordPress Upgrade Functions. Old file, must not be used. Include * wp-admin/includes/upgrade.php instead. * * @deprecated 2.5.0 * @package WordPress * @subpackage Administration */ _deprecated_file( basename(__FILE__), '2.5.0', 'wp-admin/includes/upgrade.php' ); require_once(ABSPATH . 'wp-admin/includes/upgrade.php'); |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
function the_author( $deprecated = '', $deprecated_echo = true ) { if ( ! empty( $deprecated ) ) { _deprecated_argument( __FUNCTION__, '2.1.0' ); } if ( true !== $deprecated_echo ) { _deprecated_argument( __FUNCTION__, '1.5.0', /* translators: %s: get_the_author() */ sprintf( __( 'Use %s instead if you do not want the value echoed.' ), '<code>get_the_author()</code>' ) ); } if ( $deprecated_echo ) { echo get_the_author(); } return get_the_author(); } |
_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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/** * Main function for returning orders, uses the WC_Order_Factory class. * * @since 2.2 * @param mixed $the_order Post object or post ID of the order. * @return WC_Order|WC_Refund */ function wc_get_order( $the_order = false ) { if ( ! did_action( 'woocommerce_init' ) ) { _doing_it_wrong( __FUNCTION__, __( 'wc_get_order should not be called before the woocommerce_init action.', 'woocommerce' ), '2.5' ); return false; } return WC()->order_factory->get_order( $the_order ); } |
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.