PHP 8.6: what to check before you upgrade

PHP 8.6.0 came out today. I wouldn't move a production project to it right away, but I wouldn't wait until the end of 8.5's support on 31 December 2029 either. I'd move when 8.6 has settled enough, and the calendar doesn't decide that. What decides it is when your framework, your packages and your own tests run on it without trouble.

8.6.0 includes the security fixes that 8.5.13, 8.4.28, 8.3.37 and 8.2.36 also got today. I wrote them up in a separate article. If your servers run 8.2–8.5, do that update first. There is no hurry for 8.6.

The short version

  1. Don't put 8.6 on a production server today. Add an 8.6 job to your CI and see what it reports.
  2. Run composer why-not php 8.6 to see which package still blocks it.
  3. If you use native PHP sessions, go through the three new session defaults (below).
  4. Search your own code and the vendor folder for the functions that are being deprecated.
  5. On 8.2? Its security support ends on 31 December 2026. Your realistic target is 8.4 or 8.5, not 8.6.

When to upgrade

I'd wait for three things:

  • Your framework officially supports it. Laravel's support table lists PHP 8.2–8.5 for Laravel 12 and 8.3–8.5 for Laravel 13. Neither includes 8.6. Laravel 12 gets security fixes until 24 February 2027 and Laravel 13 until 17 March 2028, so nothing forces you.
  • Your packages allow it. composer why-not php 8.6 shows which package's version constraint rules out 8.6. The real PHP and extension requirements are checked by composer check-platform-reqs, run in the environment where the application will run. According to Composer's documentation it ignores the config.platform override and checks the real platform. If your composer.json has config.platform.php, install and update follow that declared version, so keep it in mind when you try 8.6.
  • Your own tests run on it without warnings. The next two sections are about that.

These three conditions are a checklist for your own project. They say nothing about how stable 8.6 is in general: the first patch releases and other people's experience will show that.

What can break?

The migration guide on php.net lists a lot of small things. These matter most in an average PHP or Laravel project.

Session defaults. Three defaults change:

  • session.use_strict_mode goes from 0 to 1. PHP rejects an uninitialised session ID. If your custom session handler accepts external IDs, it needs SessionUpdateTimestampHandlerInterface::validateId() and SessionIdInterface::create_sid(), or you set the option back to 0.
  • session.cookie_httponly goes from 0 to 1. The session cookie is hidden from document.cookie. If JavaScript reads it, set it back to 0.
  • session.cookie_samesite was unset and becomes Lax. The cookie isn't sent on cross-site requests, except for top-level navigations with safe methods. If a POST from another site has to see the session, you need None plus session.cookie_secure = 1.

Laravel News says Laravel manages its own session cookies, so most applications won't notice. Where native PHP sessions run (an old application, a WordPress plugin, custom code), it's worth a look.

trim(), ltrim() and rtrim() now strip the form feed (\f) too. If you don't want that, pass the character list explicitly.

Errors that used to be swallowed now show up. fclose(), file_put_contents() and copy() return false when flushing or closing fails (a full disk, for example). Before, that went unnoticed. preg_grep() also returns false on a PCRE error instead of a partial array. Many functions throw ValueError for a NUL byte in a filename or parameter (file_exists(), getenv(), putenv(), is_file() and the like) and for values outside the allowed range. session_encode() returns "" for an empty session, not false.

For whoever runs the server: when PHP cannot allocate any more memory (the migration guide calls this a hard OOM condition, and it says nothing about the usual memory_limit being exceeded), it now calls abort() instead of exit(1). The exit code is then 134, and a core dump may appear. If your monitoring script watches for exit code 1, it won't see this.

A few subtler behaviour changes: a by-reference foreach may visit elements it used to skip, a < or > after an unpack() format code is now an endianness modifier (the key of s<value becomes value, not <value), and array_intersect() converts values to strings at a different point, which can change the order of warnings.

What gets deprecated?

These still work, but you get a warning, and they may become errors in 9.0. The important ones:

  • return inside a finally block (a compile-time notice: it discards the exception and overwrites the value from try/catch);
  • is_double(), is_long(), is_integer() and doubleval(): use is_float(), is_int() and floatval();
  • spl_object_hash(): use spl_object_id();
  • mb_ereg*, mb_split() and related functions, because Oniguruma has been unmaintained since April 2025: use PCRE with the u modifier;
  • strcoll() and SORT_LOCALE_STRING: use intl's Collator. This matters especially for Hungarian applications, where sorting accented letters depends on the locale;
  • the third parameter of define();
  • passing an object to array_walk(), http_build_query() and mb_convert_variables(): convert it to an array with get_object_vars() first. It isn't a drop-in swap everywhere: array_walk() then modifies the array you passed, not the properties of the original object, and http_build_query() may need a recursive conversion for nested objects;
  • let and is as the name of a class, interface, trait, enum, function or constant, and _ as a constant name or use alias (functions named _, including the gettext _() alias, are not affected);
  • a session handler that doesn't implement both create_sid() and validateId().

Search your own code, and the vendor folder too, because your packages may use them:

bash
grep -rnE '\b(is_double|is_long|is_integer|doubleval|spl_object_hash|metaphone|strcoll|mb_ereg[a-z_]*|mb_split)\(' --include='*.php' app src
grep -rn 'SORT_LOCALE_STRING' --include='*.php' app src

# file names only, from your packages
grep -rlE '\b(is_double|is_long|is_integer|doubleval|spl_object_hash)\(' --include='*.php' vendor

Adjust the folder names (app, src) to your project. A return statement inside finally is hard to find with a search like that. For that one, run your tests with error_reporting = E_ALL, because you only get the compile-time notice when the file is loaded. I haven't checked whether php -l alone shows it.

Which new features matter?

The headline additions (you don't need to upgrade for these):

  • partial function application: a ? or ... placeholder gives you a Closure that waits for the remaining arguments;
  • the clamp() function;
  • default values for readonly properties;
  • the #[\Override] attribute on class constants and enum cases;
  • the \Time\Duration class with nanosecond precision;
  • JSON error messages that include the position (for example Syntax error near location 3:12), which can help when hunting API errors.

php.net says printf(), JSON encoding and array_map() with a first-class callable got faster. I found no measured numbers, so I'm not claiming any size of speedup either.

How to try it

Don't start on your server. Add an 8.6 job to your CI where failures are allowed for now, and run the full test suite on it with error_reporting = E_ALL. The list of warnings you get tells you how much work is ahead. If your CI environment doesn't offer 8.6 yet, that's information too: it's too early.

If that list is short and composer why-not php 8.6 shows no problem either, you can plan the upgrade. If it's long, that's fine too: you can fix those items on your current PHP version in the meantime, because replacing the deprecated functions works on 8.4 and 8.5 as well.

Need a hand?

I build and upgrade PHP and Laravel applications. If you need help preparing the upgrade, setting up CI or going through old code, get in touch.


Sources

All articles →