You’ve just updated a plugin, theme, or even PHP on your WordPress site, and suddenly it happens: a Deprecated: message appears. What’s going on? Is the plugin broken? Is it time to send a concerned message to support?
Hey, I’m Doeke, a senior developer at GravityKit. In this post, I’ll explain what deprecations are in WordPress, why you shouldn’t worry about them, and how to use them (correctly) as a developer.
What are deprecations?
Deprecation notices are the canary in the coal mine. They are here to help. Please note that I said “notices” and not “errors”! This is because a deprecation is not an error.
Rather, it is a little heads-up message, informing you that some functionality your website is using will no longer work in the near future. However, at the current point in time, it still works. Deprecation notices give you time to change your website to avoid any real problems later on.
// Example deprecation notice
Deprecated: Return type of Acme\CRM\Contact::offsetGet($key) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice.Where do deprecations come from?
A deprecation notice can originate from one of two sources: primarily from PHP itself (including its extensions), and secondarily from userland code—such as plugins or themes.
PHP core deprecations
The PHP language has been evolving rapidly in recent years. At the time of writing, the latest version is PHP 8.4. In almost every PHP version, some functionality is being deprecated or has behavior that is going to change.
A behavior change might include a function parameter that no longer allows certain value types or one that becomes required moving forward. These changes are usually for the better, but they can impact existing code. Therefore, PHP will issue deprecation notices about these changes.
PHP userland deprecations
The second place where deprecations can originate is anywhere PHP code is written, like your plugins or themes. This is also known as a “userland”.
The creators of these plugins/themes are usually updating their code all the time. They add new functionality to enhance your experience of their product. Sometimes, this requires changing existing code or functionality that you might be using or extending. They will trigger a deprecation notice to let you know of this change ahead of time.
Plugins may also issue deprecations when the underlying software they rely on changes a feature, requiring adjustments to maintain compatibility. Take our GravityCharts add-on for example: it uses Chart.js under the hood. If Chart.js itself removes or changes functionality in the future, we might need to deprecate certain features to keep our add-on up-to-date.
What can I do to hide deprecation messages?
Since deprecations are not errors, they should not be visible on a production site. Deprecation notices serve as a helpful heads-up to developers. So, if you are not a developer, your website should ignore these messages.
Hiding deprecations on any PHP website
A good practice for production websites is to not display any errors. This is because errors might include sensitive information that would make an attack on your site easier, and it also reflects poorly on your company. The following snippet will hide most errors from your website:
error_reporting( E_ALL & ~E_DEPRECATED & ~E_STRICT );
ini_set( 'display_errors', 0 );
ini_set( 'log_errors', 1 );You can add this line to the index.php file in the public entry folder of your website, just below the <?php line. It will ensure errors are not displayed to the user, but they are still written to the error log (except deprecation notices and strict errors). This way, the end user will not be bothered by them, but you can still inspect any errors through the log.
Hiding deprecations on a WordPress website
WordPress defines a global constant that determines whether debug information is shown. This constant is called WP_DEBUG and is located in your wp-config.php file. On a production website, this constant needs to be set to false.
define( 'WP_DEBUG', false );This will hide any deprecations (and other warnings) that are emitted from WordPress or any plugins.
If you want to log any errors without making them visible to the end user, you must have debugging enabled and debug visibility disabled. By setting the WP_DEBUG_LOG constant to true, you can log everything to wp-content/debug.log or specify a particular path by providing the absolute path file.
define( 'WP_DEBUG', true ); // Enable debugging.
define( 'WP_DEBUG_DISPLAY', false ); // Hide the errors and warnings from the end user.
define( 'WP_DEBUG_LOG', true ); // Log to "wp-content/debug.log".
// Or:
define( 'WP_DEBUG_LOG', '/etc/log/wordpress-debug.log' ); // Log to a specific path.It is advisable to use this sparingly on a production site. When you have a lot of traffic, the debug log will quickly fill up, which can take up a lot of disk space.
Staying up-to-date
Although hiding notices is advisable for production sites, it’s even more important to keep your WordPress installation and plugins fully up to date.
As I mentioned previously, PHP will often emit deprecations in new versions. WordPress and plugin developers should be aware of this, and will most likely update their products to account for these deprecations. Updating WordPress and plugins is therefore a great way to protect your website from potential issues in the future.
What does GravityKit do to avoid deprecations?
At GravityKit, we understand that getting a deprecation notice can be jarring. Though we urge you to disable deprecation notices on a production site, we know some users may still encounter them. That’s why we take the following steps to prevent them as much as possible:
1. Run automated tests against our dependencies’ latest versions
Since our add-ons rely heavily on Gravity Forms, we make sure to run our automated tests against the latest version of Gravity Forms. This means that when they add a deprecation, we can spot it early and fix it before releasing a new version.
Of course, a new release of Gravity Forms can precede a patched version of our add-ons, so this cannot guarantee you will not see any deprecations. But we do fix them quickly and release patches as necessary.
2. Tag our deprecations with the @deprecated tag
Since we create our own plugins and add-ons, we occasionally deprecate functionality. When it comes to hooks, we deprecate them using do_action_deprecated() and apply_filters_deprecated() so any developer using that action or filter knows to look into a replacement.
For functions and methods we also add a @deprecated annotation to it. Because most IDEs (like VS Code and PhpStorm) will visually show the deprecation, this means that a developer can spot these deprecations while developing, allowing them to adjust as soon as possible.
3. Ensure the use of Semantic Versioning
In order to communicate deprecations and other (possibly breaking) changes, we use Semantic Versioning (SemVer). This is a versioning strategy that reflects the impact of a new release through the plugin’s version number.
A SemVer version number consists of 3 numbers, separated by a dot (.). For example: 2.4.16. The format of this version number is <major>.<minor>.<patch>.
The patch number goes up whenever a bug is fixed or a tiny enhancement has been made; for example, a new action or filter was added. A patch release does not add any new functionalities, and it should not include any breaking changes.
A minor version introduces new functionality, things the plugin or add-on could not do before. However, a minor version can still contain bug fixes.
The major version is the one that is updated the least. It introduces a major change in how the plugin or add-on operates. It is likely (partly) rewritten and introduces potential breaking changes to any plugin or theme that builds on top of its old functionality.
When GravityKit introduces deprecations, we do so in patch versions (example: a renamed filter) and minor versions (example: a method that becomes obsolete due to a new feature). Because removing a method or filter would be a breaking change, these deprecations are only removed in the next major version.
The general rule of thumb is that if you rely on our plugins and add-ons with customizations, updating within the same major version should not cause any issues. However, when it comes to major updates, we suggest testing your customization on the new version before running the update.
Please note: While PHP uses a three-digit version number, they do not use SemVer. This means that an upgrade from PHP 8.4 to 8.5 could contain breaking changes and remove any deprecated functionality! So please test your website thoroughly on a new PHP version before upgrading.
In summary
If you are a developer who deprecates functionalities, strive to assist users and other developers as much as possible by using @deprecated annotations and the appropriate WordPress helper methods.
For users—ensure that you keep WordPress and your plugins up-to-date, and don’t be alarmed by a deprecation notice. However, be concerned when your production website displays them.
If you’re encountering deprecation notices and don’t know how to change the settings we mentioned, you can use the following email template to send to your developer or hosting partner:
Dear [Developer's or Hosting Partner's Name],
I recently noticed deprecation notices appearing on my WordPress website, and I would appreciate your help in resolving them or, at the very least, hiding them from being visible on the website.
Could you please check my website’s error reporting settings and ensure that deprecation notices are hidden? Here are a few key adjustments that may be necessary:
- Verify that WP_DEBUG is set to false in wp-config.php.
- Update any outdated plugins, themes, or PHP versions if needed.
- Adjust the error reporting settings in PHP to suppress deprecation messages in production:
error_reporting( E_ALL & ~E_DEPRECATED & ~E_STRICT );
ini_set( 'display_errors', 0 );
ini_set( 'log_errors', 1 );
If these notices indicate a compatibility issue, please let me know whether any updates or adjustments are required.
Thank you for your help!
Helpful tips right in your inbox.
Subscribe to our weekly newsletter for tips, special offers, and more!
Helpful tips right in your inbox.
Subscribe to our weekly newsletter for tips, special offers, and more!