Stay ahead of PHP deprecations by learning how to refactor legacy code and manage warnings effectively. Ensure your application is secure, efficient, and compatible with future PHP versions.
You upgrade PHP on a Friday, and by Monday your error log is full of “Deprecated:” lines you have never seen before. Nothing is broken yet. That is exactly the trap. A deprecation notice is PHP telling you, calmly, that a function you lean on is on its way out. Ignore it long enough and a future upgrade turns that quiet warning into a fatal error.
This guide walks through how to read those notices, find the code that triggers them, and refactor it without breaking things. No panic, no rewrite-everything advice. Just the practical steps.
Table of Contents
- Understanding Deprecation Notices in PHP
- Common Deprecated Functions in PHP
- Strategies for Updating Code
- Handling Deprecation Notices Gracefully
- Best Practices for Managing Deprecations
- Conclusion
Understanding Deprecation Notices in PHP
A deprecation notice means a feature still works, but the PHP team plans to remove it. It is a heads-up, not an error. You usually get a window of a major version or two to move off it before it disappears for good. That window is the whole point. Use it.
The notices land in your error log, and on screen if display_errors is on in development. They read like this:
<?php
Deprecated: Function create_function() is deprecated in /path/to/file.php on line 20
Internally these are E_DEPRECATED notices, which is a separate error level from E_NOTICE. Keep that distinction in mind; it decides what you can safely hide later without also hiding your deprecation warnings.
Why Deprecation Happens
Features get retired for a few honest reasons:
- Security: some old functions handled input in ways that are hard to make safe, so a better-guarded alternative replaces them.
- Performance: as the engine improves, faster approaches show up and the slower legacy ones get phased out.
- Maintainability: trimming redundant or surprising behavior keeps the language smaller and steers everyone toward clearer code.
Common Deprecated Functions in PHP
Here are the ones you are most likely to hit, oldest to newest. Watch the difference between deprecated (still runs, just warns) and removed (gone, hard fatal error):
create_function(): deprecated in PHP 7.2 and removed in PHP 8.0. Use a real anonymous function (closure) instead; you get proper scope and no string-eval risk.each(): deprecated in PHP 7.2 and removed in PHP 8.0. Replace it with a plainforeachloop.- Dynamic (undeclared) properties: deprecated in PHP 8.2. Writing to a property you never declared now warns. Declare the property, or add the
#[\AllowDynamicProperties]attribute if you genuinely need the old behavior. utf8_encode()andutf8_decode(): deprecated in PHP 8.2. Reach formb_convert_encoding()oriconv(), which are explicit about the encodings you are converting between."${var}"string interpolation: deprecated in PHP 8.2. Switch to"$var"or"{$var}"instead.
Strategies for Updating Code
Clearing deprecations is less about heroics and more about a repeatable loop: find them, learn the replacement, ship the fix in pieces.
1. Identify Deprecated Features
You cannot fix what you cannot see, so start by surfacing every offender:
- Read your error logs: deprecation notices land there first, and they name the file and line, so you get a punch list for free.
- Run static analysis: tools like PHPStan and Psalm scan the whole codebase up front and flag deprecated calls before they ever run.
2. Research the Replacement
Once you know what is deprecated, find its modern counterpart before you touch anything. Usually PHP already ships one. Closures replace create_function(), foreach replaces each(), and the multibyte functions replace the old UTF-8 helpers. Read the manual note for the version you are targeting; it almost always spells out the recommended swap.
3. Update Incrementally
On a large codebase, do not try to clear every notice in one branch. Prioritize the calls to functions that are already removed in the version you are moving to, since those are the ones that will actually crash. The rest can follow in smaller, reviewable batches.
Handling Deprecation Notices Gracefully
Handling deprecations well is mostly about seeing them early in development and never letting them leak to production users.
1. Turn Deprecation Warnings On in Development
Make sure your dev environment actually reports deprecations. Set error_reporting in php.ini:
<?php
error_reporting = E_ALL & ~E_NOTICE
This works because E_ALL already includes E_DEPRECATED. Since E_DEPRECATED is its own level, masking out E_NOTICE quiets the noisy notices without hiding a single deprecation. On production, keep display_errors off and send these to a log instead, so real users never see them.
2. Guard Calls With Feature Detection
When you need one codebase to run across PHP versions, check that a function exists before you call it. It keeps older environments from fataling:
<?php
if (function_exists('new_function')) {
new_function();
} else {
// Use older function as a fallback
}Best Practices for Managing Deprecations
A few habits keep deprecations from ever piling up into a crisis:
1. Keep PHP Reasonably Current
Upgrading in small, regular steps means you deal with a handful of deprecations at a time instead of years of them at once. It also keeps you on a version that still gets security patches, which matters more than any single warning.
2. Stop Reaching for Deprecated Functions
When you write new code, skip functions that are already flagged and use the current alternative from the start. Well-maintained frameworks such as Symfony and Laravel track PHP releases closely, so leaning on their APIs keeps you off the deprecated paths without much thought.
3. Test Before You Refactor
Put automated tests around the code you are about to change first. Swapping a deprecated function is exactly the kind of edit that quietly shifts behavior, and a test suite is what catches it before your users do.
4. Watch the Release Notes
Every PHP release ships a migration guide listing what is deprecated and what is finally removed. Skim it when a new version lands and you will know what is coming instead of finding out from a crash.
Conclusion
Deprecation notices are not the emergency; ignoring them is. Treat each one as a scheduled task with a deadline you set, not the language sets. Surface them with your logs and static analysis, fix them in small batches with tests behind you, and stay on a supported PHP version.
Do that, and upgrades stop being the scary Friday deploy and become routine. Your codebase keeps working, and you are never the person debugging a fatal error that PHP warned you about two versions ago.