Learn how to handle PHP deprecation warnings effectively. Discover how to update outdated code and manage deprecated features in your PHP applications for improved security and performance.
You upgrade PHP, reload the site, and there it is in the logs: Deprecated: .... Nothing broke. The page still works. So it’s tempting to scroll past it and move on.
Don’t. A deprecation notice is PHP telling you the truth early. The function or feature still runs today, but it’s on the way out, and one future major version will remove it for good. When that happens, the warning you ignored turns into a fatal error. This guide walks through reading those notices, fixing the code behind them, and keeping the noise out of your users’ faces while you do it.
Table of Contents
- Understanding Deprecation Notices
- Why Handle Deprecation Notices?
- Identifying Deprecation Warnings in Your Code
- Updating Your Code to Handle Deprecations
- Using Error Handling to Manage Deprecations
- Best Practices for Deprecation Management
- Conclusion
Understanding Deprecation Notices
A deprecation notice is a soft warning. The code keeps working in the current version, but the PHP team has flagged it for removal in a future release. Think of it as a countdown you can still act on. Notices are emitted at the E_DEPRECATED error level (value 8192), which is part of E_ALL, so once reporting is on you’ll see them.
Here’s what one looks like. This uses ereg(), deprecated back in PHP 5.3 and later removed entirely in PHP 7.0:
<?php
/**
* Example of deprecated PHP code using the ereg() function, which was deprecated in PHP 5.3.
*/
$pattern = '^[a-zA-Z]+$';
$string = 'HelloWorld';
// Deprecated function that triggers a deprecation warning
if ( ereg( $pattern, $string ) ) {
echo 'Match found!';
}
The fix is to move to preg_match(), the PCRE-based replacement. And ereg() isn’t ancient history. Recent PHP versions keep the same pattern going: PHP 8.2 deprecated dynamic properties (assigning to an undeclared property on an object), utf8_encode() and utf8_decode(), and the ${} style of string interpolation. PHP 8.1 deprecated strftime(). PHP 8.0 didn’t just deprecate, it removed each() and create_function() outright. Every one of those started life as a notice you could have seen coming.
Why Handle Deprecation Notices?
Ignoring a notice costs you nothing today and a lot later. Three honest reasons to deal with them now:
- Avoid a future outage: the version that removes the feature turns your working code into a fatal error. Better to fix it on your schedule than during an emergency upgrade.
- Smaller upgrade steps: a codebase with zero notices upgrades cleanly. One that has ignored them for three major versions is a wall of breakage all at once.
- Occasionally security or correctness: some removals do close a security gap or a broken behavior, though most are cleanup and API tidying. Don’t assume every deprecation is a security fix, but don’t assume none of them are either.
Identifying Deprecation Warnings in Your Code
You can’t fix what you can’t see. In development, turn reporting all the way up so deprecations surface. E_ALL already includes E_DEPRECATED:
<?php
/**
* Enable error reporting to capture deprecation warnings.
*/
error_reporting( E_ALL );
Do this in dev and staging, not production. On a live site you want these logged, not printed to visitors. Set display_errors = Off and log_errors = On in production, then read them from your error log.
Updating Your Code to Handle Deprecations
Seeing the notice is half the job. The real work is changing the code so the notice goes away for good.
1. Replace Deprecated Functions
Most deprecated functions have a documented replacement. Swap ereg() for preg_match(). Note the pattern gains delimiters (/.../) that ereg() didn’t need:
<?php
/**
* Using preg_match() to replace the deprecated ereg() function.
*/
$pattern = '/^[a-zA-Z]+$/';
$string = 'HelloWorld';
if ( preg_match( $pattern, $string ) ) {
echo 'Match found!';
}2. Update the Pattern, Not Just the Call
Some deprecations aren’t a one-for-one function swap. Dynamic properties in 8.2 are a good example: the fix is to declare the property on the class, or add the #[\AllowDynamicProperties] attribute if you genuinely need the old behavior. On a large codebase you won’t clear every notice in one sitting, and that’s fine. Fix the highest-traffic paths first, and lean on the tools below to find the rest.
Using Error Handling to Manage Deprecations
While you work through the backlog, you don’t want deprecation noise leaking to users or drowning your logs. A custom error handler lets you catch just the deprecations and route them where you want. set_error_handler() does receive E_DEPRECATED, so this works:
Logging Deprecation Warnings
<?php
/**
* Custom error handler to log deprecation warnings without displaying them to users.
*/
function custom_error_handler( $errno, $errstr, $errfile, $errline ) {
if ( $errno === E_DEPRECATED ) {
error_log( "Deprecation Warning: $errstr in $errfile on line $errline" );
return true; // Prevent PHP's default error handler from running
}
return false;
}
// Set the custom error handler
set_error_handler( 'custom_error_handler' );
// Example of deprecated function call
ereg( '^[a-zA-Z]+$', 'HelloWorld' ); // This will be logged instead of displayedOne caution: this manages the symptom, not the cause. Logging a deprecation is a holding pattern that buys you time to fix the code. It is not the fix. If you leave the handler in and never touch the underlying call, the removal version will still break you.
Best Practices for Deprecation Management
Deprecation handling isn’t a one-time task, it’s a habit. A few practices that keep it from piling up:
1. Upgrade PHP Regularly
Track PHP releases and move to current versions as they land. Small, frequent jumps surface a handful of notices each. Skipping five versions surfaces all of them at once, on a deadline.
2. Let Tools Find the Deprecated Code
You don’t have to grep by hand. PHPCompatibility (a ruleset for PHP_CodeSniffer) flags code that won’t work on a target PHP version. PHPStan reports calls to deprecated functions during static analysis. And Rector can rewrite a lot of deprecated patterns for you automatically. Run them in CI so a new deprecation fails the build instead of sneaking in.
3. Test in Staging First
Always run a new PHP version in staging before production. Point it at real traffic patterns and read the logs. It’s the cheapest place to find what breaks.
4. Refactor a Little at a Time
Clear deprecations in small, regular passes rather than one heroic sprint before a forced upgrade. A steady trickle keeps the count near zero and the codebase easy to move forward.
Conclusion
Deprecation notices are a gift, not an annoyance. They tell you exactly what will break and give you time to fix it before it does. Turn reporting on in dev, log them out of your users’ way, replace the flagged code, and let PHPStan or Rector catch the rest.
Do that on a regular cadence and PHP upgrades stop being scary events. They become quiet, boring bumps, which is exactly what you want them to be.