Deprecation in WooCommerce Core

Deprecation is a method of discouraging usage of a feature, or practice, in favour of something else without breaking backwards compatibility or totally prohibiting it’s usage. To quote the Wikipedia article on Deprecation:

While a deprecated software feature remains in the software, its use may raise warning messages recommending alternative practices; deprecated status may also indicate the feature will be removed in the future. Features are deprecated rather than immediately removed, to provide backward compatibility and give programmers time to bring affected code into compliance with the new standard.

There are various reasons why a function, method, or feature may be deprecated. To name a few:

• We may want to remove a function we do not use any longer.
• We may decide to change or improve how a function works, but due to breaking backwards compatibility we need to deprecate the old function instead.
• We may need to make naming conventions standardised.
• We may find opportunities to merge similar functions to avoid reusing the same code in difference places.

In WooCommerce 2.7, we’ve done quite a bit of deprecation mostly due to the new CRUD system. We want developers to make use of the new CRUD objects where possible, but we don’t want to break the old way of accessing data so developers have some time to migrate.

We understand first hand that the process of updating extensions can be made difficult due to the need to support older versions as well as the latest version of WooCommerce, but we want to emphasise the fact that whilst notices are not ideal or attractive, they are just warnings–Store owners; Deprecation warnings do not mean your store is broken, it just serves as a reminder that code will need to be updated.

How do we deprecate functions?

When we deprecate something in WooCommerce, we take a few actions to make it clear to developers and to maintain backwards compatibility.

1. We add a docblock to the function/method showing what version the function was deprecated. e.g. @deprecated 2.x.x
2. We add a warning notice using our own wc_deprecated_functionfunction which shows what version, what function, and what replacement is available. More on that in a bit.
3. We remove usage of the deprecated function throughout of codebase.

The function or method itself is not removed from the codebase. This preserves backwards compatibility until removed (usually over a year or several major releases into the future!).

I mentioned wc_deprecated_function above – this is our own wrapper for the _deprecated_function WordPress function. It works very similar except for that it forces a log entry instead of display regardless of WP_DEBUG mode during AJAX events so that AJAX requests are not broken as a result of the notice.

What happens when a deprecated function is called?

If an extension or theme uses a deprecated function, you may see a warning like the following example:

Notice: woocommerce_show_messages is deprecated since version 2.1! Use wc_print_notices instead. in /srv/www/wordpress-default/wp-includes/functions.php on line 3783

This tells you what is deprecated, when, where, and what replacement is available.

Notices and warnings are usually shown inline but there are some plugins you can use to collect them and shown nicely in the footer of your site. Personally, I Use Query Monitor.

Warnings in production (store owners read this!)

Showing PHP notices and warnings (or any error for that matter) is highly discouraged on your production stores. They can reveal information about your setup which a malicious user could use. Make sure they are hidden from public view, and optionally logged instead.

In WordPress you can do this by adding or modifying some constants in your wp-config.php file.

define( 'WP_DEBUG', false );

On some hosts, errors may still be visible due to the hosts config. To force them to not display you can add this to your wp-config.php file too:

@ini_set( 'display_errors', 0 );

To log notices instead of displaying them, use:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

The default location of the WordPress error log is wp-content/debug.log.

Dealing with deprecation as a developer

Whilst it would be nice to just support the latest versions and remove any deprecated code immediately, this often isn’t possible (unless you’re making plugins for your own personal use). In a perfect world, WordPress would have some form of versioning system whereby you could define what versions X version of your own plugin supported and WordPress could ensure a suitable version is installed. Alas, this mechanism does not exist, so approaching deprecation can be a little tricky.

Therefore, your approach to deprecation may vary depending on what type of plugin you’re offering.

A basic example could be to use function_exists and method_existscalls and run code conditionally (this is preferred over detecting versions installed).

So for example, with the CRUD update say you were getting a products ID you may have been using:

$id = $product->id;

As this will throw a warning in 2.7 you could swap this to:

if ( method_exists( $product, 'get_id' ) ) {
    $id = $product->get_id();
} else {
    $id = $product->id;
}

Or for brevity:

$id = method_exists( $product, 'get_id' ) ? $product->get_id() : $product->id;

This uses the most up to date method of getting the ID when possible. If you had a plugin which did a lot of the above logic, you could use some other approaches such as:

• Having wrapper functions in your code to return the correct value based on what is available.
• Having different files or classes based on version so they can be removed when support is dropped easily.
• If the plugin is not mission critical, disabling your custom functionality if the minimum version is less than 2.7 and showing a warning before upgrade.

If you do run into a scenario where you want to know the version being ran, you can use our constant and version compare:

if ( version_compare( WC_VERSION, '2.7', '<' ) ) {
    // Older than 2.7
} else {
    // 2.7+
}

We’ll be posting examples in the coming weeks showing how we’re updating our own extensions. Stay tuned!