PHP 8.6: New Features, Deprecated Functions, and a Practical Migration Guide
Upgrade to PHP 8.6 with before-and-after examples for deprecated PHP functions, MySQLi, mbstring, CSV, sessions and a practical migration checklist.
PHP 8.6.0 was released on November 19, 2026. The headline features are interesting, but for developers maintaining real websites the urgent question is often different: which lines of existing code will start emitting deprecation notices, and how should they be rewritten?
This guide puts the migration work first. Each example identifies a deprecated API, shows a replacement, and highlights where a mechanical search-and-replace would be dangerous. A deprecation notice is not the same as an immediate fatal error: it warns that code needs attention, often before a future major version removes the API.
1. Check your runtime before touching production
Run these commands in the same PHP environment that serves the application (CLI and web PHP may use different binaries and settings):
php -v
php -m
php --ini
Check extensions used by the project, especially mbstring, mysqli and intl. Verify that the framework, CMS, extensions and hosting environment explicitly support PHP 8.6; do not infer compatibility merely because a site starts.
In a staging environment, log all errors while keeping diagnostic messages out of public HTML:
<?php
error_reporting(E_ALL);
ini_set('log_errors', '1');
ini_set('display_errors', '0');
These runtime settings are useful for a controlled test. Prefer configuring logging at server level for long-running environments; ensure the error log is writable and private. A Deprecated message is actionable even when the page still renders.
2. Quick reference: deprecated APIs and what to use instead
| Deprecated in PHP 8.6 | Recommended approach | Migration caveat |
|---|---|---|
is_integer(), is_long() |
is_int() |
Direct aliases |
is_double() |
is_float() |
Direct alias |
doubleval() |
floatval() |
Direct alias |
spl_object_hash() |
spl_object_id() |
Return type changes from string to int |
mb_ereg(), mb_eregi() |
preg_match() |
Adapt pattern syntax and Unicode flags |
mb_ereg_replace() |
preg_replace() |
Check escaping, replacement semantics and errors |
mysqli_stmt_init() |
mysqli_prepare() |
Prepare immediately |
mysqli_get_charset() |
mysqli_character_set_name() |
Only if the charset name is needed |
SplFileObject::fgetcsv() |
fgetcsv() on a stream |
Revisit stream position and CSV settings |
SplFileObject::fputcsv() |
fputcsv() on a stream |
Pass delimiter, enclosure and escape explicitly |
strcoll() |
Collator::compare() |
Requires intl; choose a locale |
SORT_LOCALE_STRING |
Collator::sort() / asort() |
Locale behavior can change |
spl_classes() |
ReflectionExtension::getClassNames() |
Inspect the appropriate extension |
Third argument of define() |
Omit the argument | The old case-insensitive mode is gone |
return in finally |
Return outside finally |
Avoid suppressing exceptions |
Object passed to array_walk() |
get_object_vars() first |
By-reference edits may no longer mutate the object |
metaphone() |
A maintained phonetic implementation | No drop-in core replacement |
Some APIs have no exact replacement. The correct migration may require changing the design rather than renaming a function. See the official PHP 8.6 deprecations list.
3. Simple aliases: safe, fast fixes
Before — deprecated:
<?php
if (is_integer($quantity) && is_double($price)) {
$total = doubleval($price) * $quantity;
}
After:
<?php
if (is_int($quantity) && is_float($price)) {
$total = floatval($price) * $quantity;
}
The aliases have the same semantics. Do not assume that is_float(40) is true: an integer remains an integer. That behavior was already present before the migration.
For a string amount, floatval() is a conversion, not a money-safe decimal representation. Keep the project's existing money-handling strategy rather than changing it as part of an unrelated PHP upgrade.
4. Migrating mbstring regular expressions
The mb_ereg* family is deprecated because its underlying Oniguruma regex engine is no longer maintained. PHP recommends PCRE for many use cases, but the pattern dialects are not identical.
Before:
<?php
$isReference = mb_ereg('^[0-9]+$', $reference) !== false;
After (ASCII digits only):
<?php
$isReference = preg_match('/^[0-9]+$/D', $reference) === 1;
Here the D modifier makes $ match only at the end of the subject. For Unicode text, use an appropriate UTF-8 pattern and the u modifier:
<?php
$isName = preg_match('/^\p{L}+(?:[ -]\p{L}+)*$/uD', $name) === 1;
Before — replacement:
<?php
$clean = mb_ereg_replace('[[:space:]]+', ' ', $text);

After — replacement:
<?php
$clean = preg_replace('/\s+/u', ' ', $text);
if ($clean === null) {
throw new RuntimeException('Regular expression failed');
}
The two patterns may differ on some Unicode whitespace. For real migrations, test accented characters, newlines, invalid UTF-8, capture groups and backreferences against actual project data. Do not mass-replace every mb_ereg call without reviewing the expression.
5. MySQLi: prepare a statement in one step
Before — deprecated:
<?php
$stmt = mysqli_stmt_init($mysqli);
mysqli_stmt_prepare($stmt, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
After:
<?php
$stmt = mysqli_prepare($mysqli, 'SELECT name FROM users WHERE id = ?');
mysqli_stmt_bind_param($stmt, 'i', $userId);
mysqli_stmt_execute($stmt);
With the object-oriented API, use $mysqli->prepare($sql) instead of $mysqli->stmt_init() followed by prepare(). Keep your existing error handling and close statements appropriately.
The separate mysqli_get_charset() API is also deprecated. If you only need the current charset name:
<?php
$charsetName = mysqli_character_set_name($mysqli);
This is not a replacement for all fields of the old charset-information object. If the code depends on collation metadata, inspect what it actually needs and query the server appropriately.
6. CSV: replace deprecated SplFileObject CSV methods
The CSV-specific methods on SplFileObject are deprecated. For new and migrated code, use the stream-based fgetcsv() and fputcsv() functions.
Before:
<?php
$file = new SplFileObject($path, 'r');
while (!$file->eof()) {
$row = $file->fgetcsv();
// Process row
}
After:
<?php
$handle = fopen($path, 'rb');
if ($handle === false) {
throw new RuntimeException('Cannot open CSV file');
}
try {
while (($row = fgetcsv($handle, 0, ',', '"', '')) !== false) {
// Process row
}
} finally {
fclose($handle);
}
The empty escape argument disables PHP's proprietary escape mechanism; test this choice against the format your source system exports. Check blank lines, headers, delimiters, embedded newlines and encoding. This example illustrates the API change, not a universal CSV parser.
For writing, use fputcsv($handle, $fields, ',', '"', ''). Preserve the original file's expected dialect.
7. Object identity: spl_object_hash() is not a content hash
Before:
<?php
$key = spl_object_hash($object);
After:
<?php
$key = spl_object_id($object);
The replacement returns an integer, not a string. If keys are serialized, stored in a database or exposed through an API, review consumers first. Neither function produces a persistent identifier across requests, and IDs can be reused after objects are destroyed. For a map keyed by live object identity, consider SplObjectStorage or WeakMap, depending on lifetime requirements.
8. A return in finally can hide failures
Before — deprecated and misleading:
<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
return []; // Overrides the result and hides exceptions
}
}
After — preserve cleanup without overriding the result:

<?php
function loadSettings(): array
{
try {
return readSettings();
} finally {
releaseTemporaryResources();
}
}
If the original code intentionally returned a fallback, move that decision into a catch block with explicit handling. Do not silently swallow an exception that should reach the caller.
9. Locale-sensitive sorting and other less obvious changes
strcoll() and the SORT_LOCALE_STRING sorting flag are deprecated. The recommended intl alternative is Collator:
<?php
$collator = new Collator('fr_FR');
$names = ['Émile', 'Alice', 'Zoé'];
$collator->sort($names);
Check that intl is installed. Locale-aware sorting is a business rule: test your expected order rather than assuming ICU and a process-global locale will always behave identically.
Other migration items deserve explicit attention:
ArrayIterator: sorting, flags and serialization methods such asasort(),ksort(),setFlags()andserialize()are deprecated. Sort the underlying array or useArrayObjectwhen its API is appropriate; do not assume an iterator and a container are interchangeable.- Custom session handlers: implement both
create_sid()andvalidateId()as required by the updated interfaces/behavior. PHP 8.6 enables stricter session defaults; test login, session rotation and persistence. __debugInfo(): use a non-nullablearrayreturn type; returningnullwas already deprecated.define(): remove the thirdcase_insensitiveargument, even when it isfalse.http_build_query()andarray_walk(): passing objects where arrays are expected is deprecated. Convert intentionally usingget_object_vars()or construct the desired array explicitly.metaphone(): no equivalent built-in PHP replacement exists. Choose and test a maintained, language-appropriate phonetic algorithm.- Reserved identifiers: names such as
let,is,readonly(function) andnamespace(class constant) have new deprecation restrictions. Rename affected declarations carefully. - Reflection: review invalid objects passed to
ReflectionProperty::setValue()and object arguments supplied when invoking static methods.
Consult the full migration guide for edge cases not covered in this practical selection.
10. Find deprecated calls in an existing project
Start with a read-only inventory. On Linux or macOS:
grep -RnE --include='*.php' \
'is_integer\(|is_long\(|is_double\(|doubleval\(|spl_object_hash\(|mb_ereg\(|mb_ereg_replace\(|mysqli_stmt_init\(|mysqli_get_charset\(' \
./src
Replace ./src with the actual directory. This text search may match comments or strings, and will miss dynamic calls, namespaced aliases and other deprecated APIs. It is a starting point, not a complete static analyzer.
For a cross-platform option, an editor's Find in Files can search for the same names. Do not edit vendor or CMS core files directly: update the upstream package or submit a patch to its maintainer.
A reproducible migration sequence
- Record the current PHP version and enabled extensions.
- Back up files and database; prepare a staging copy.
- Run the project under PHP 8.6 with deprecation logging enabled.
- Inventory warnings by file and line, then group by API.
- Fix first-party code with targeted changes; update third-party dependencies separately.
- Rerun unit/integration tests and important user journeys.
- Check forms, login, sessions, email, payments, scheduled jobs, CSV import/export and database access.
- Deploy with a rollback plan; monitor error logs after release.
Joomla and WordPress: PHP 8.6 being released does not mean every CMS version, extension or plugin supports it. Confirm compatibility with the exact versions in use and test a staging environment first. Do not use the upgrade as a reason to patch core or vendor code directly.
11. What is actually new in PHP 8.6?
Beyond deprecations, the release adds several language and runtime features:
| Feature | Practical use |
|---|---|
| Partial function application | Pre-fill arguments and obtain a callable for the remaining ones |
clamp() |
Constrain a value between a minimum and maximum |
\Time\Duration |
Represent elapsed time rather than a calendar date |
SortDirection |
Express ascending/descending direction through a standard enum |
Io\Poll |
Support stream polling in event-loop and I/O libraries |
| Defaults for readonly properties | Simplify selected immutable class declarations |
A small, immediately useful example is clamp():
<?php
// Before PHP 8.6
$percentage = min(100, max(0, $input));
// PHP 8.6
$percentage = clamp($input, 0, 100);
The code is easier to read, but the migration priority should still be compatibility testing. The other features are not necessary just to keep an existing application working. See the official release announcement.
12. Before you switch the production PHP version
Treat PHP 8.6 as a controlled upgrade, not a button to click on a busy production server. A sensible release checklist is: supported CMS and dependencies; available extensions; no unexpected deprecation flood; tests passing; verified database and session behavior; tested backups; and a rollback procedure.
Bottom line: PHP 8.6 brings useful features, but its deprecations are often where maintenance work begins. Fix the straightforward aliases first, then test behavioral migrations—especially regex, CSV, sessions and locale-sensitive operations—against real data.