Deprecation in 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.
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.
When we deprecate something in WooCommerce, we take a few actions to make it clear to developers and to maintain backwards compatibility.
- We add a docblock to the function/method showing what version the function was deprecated. e.g.
@deprecated 2.x.x
- We add a warning notice using our own
wc_deprecated_function
function which shows what version, what function, and what replacement is available. More on that in a bit. - 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.
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.
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
Note that this log can be publicly accessible. To keep it private, you can use a plugin or define it in wp-config.php
.
<?php
/**
* Plugin Name: Custom Debug Log Path
*/
ini_set( 'error_log', '/path/to/site/logs/debug.log' );
From https://woocommerce.wordpress.com/2017/01/17/deprecation-in-woocommerce-core/
WooCommerce is an open source commerce platform built for WordPress and lovingly crafted by Automattic and the WooCommerce community 💜. Come and work with us!
Contribution
- Set up development environment
- Our Git Flow
- SCSS and JS minification
- Naming conventions
- CSS SASS coding guidelines and naming conventions
- Critical Flows
- API Critical Flows
- String localisation guidelines
- Translating WooCommerce
- Deprecation in core
- Adding Actions and Filters
- Common Issues
- Writing high-quality testing instructions
Release Notes
- Release Testing Instructions
- 3.6.x notes/FAQ
- 2.6.x to 3.0.0 Developer Migration Notes
- Select2 fields not working in 3.0.x
- Thumbnail Image Regeneration in 3.3+
- Customizing image sizes in 3.3+
REST API and CLI
CRUD & Data Descriptions
- Database Description
- CRUD Objects in 3.0
- Order and Order Line Item Data
- Coupon Data
- Customer Data
- Product Data
- Data Stores
Internal APIs
Theming
- Enabling product gallery features (zoom, swipe, lightbox)
- Template File Guidelines for Devs and Theme Authors
Examples / Guides