Upgrade PHP in a development or staging environment first. For a PHP 8.4 application, begin with its dependencies and runtime configuration, then review the PHP 8.5 migration changes and exercise the application’s important workflows.
PHP 8.5 became stable on November 20, 2025. Choose a maintained patch release from the official downloads and check the support schedule. The 8.4 to 8.5 migration guide is the source for version-specific changes; this checklist helps organize your project review.
1. Record the runtime you actually use
Run these in the current environment, then repeat them in the PHP 8.5 environment:
php -v
php --ini
php -m
composer show --platformKeep the outputs with your upgrade notes. Compare loaded extensions, configuration files, and the PHP binary used by scheduled jobs and workers. Verify the web runtime separately: your terminal’s PHP version does not establish which binary serves HTTP requests.
Inventory the application’s needs, such as database drivers, image processing, internationalization, and caching extensions. An upgrade decision should cover those dependencies as well as the core PHP version.
2. Check declared dependencies on PHP 8.5
With the target PHP runtime selected, use Composer to identify declared compatibility problems:
composer prohibits php 8.5
composer check-platform-reqs --lockprohibits reports dependency constraints blocking a version. The platform check verifies PHP and extensions against the lockfile’s requirements and checks the real environment rather than an emulated config.platform value. Composer CLI documentation.
If a package blocks the upgrade, inspect its compatible release and upgrade notes. Update the dependency deliberately and review the resulting lockfile. Repeat platform checks on the installed dependencies in the target environment:
composer check-platform-reqsThese checks cannot detect every undeclared compatibility problem. Keep application tests as a separate acceptance step.
3. Review PHP 8.5 deprecations in your code
PHP 8.5 deprecates non-canonical casts. Replace (boolean), (integer), (double), and (binary) with (bool), (int), (float), and (string). The migration guide also covers semicolons after case, the backtick operator, and returning null from __debugInfo(). Official deprecated features.
For example, modernize existing casts:
// Before
$enabled = (boolean) $input;
$quantity = (integer) $count;
// After
$enabled = (bool) $input;
$quantity = (int) $count;A repository search can locate cast candidates:
rg '\((boolean|integer|double|binary)\)' src app testsUse the directories your application actually has. Inspect each result; the search may also find comments or strings. Run your existing test suite with deprecations visible in the PHP 8.5 environment. Fix warnings in owned code and track upstream dependency warnings against the relevant package.
4. Test behavior changes where they affect your application
Two examples from the official incompatible changes illustrate why passing a dependency check is insufficient:
- Loose boolean comparison of objects such as enums and internal handles now behaves consistently with boolean casting. Test code that relies on such comparisons and make the intended condition explicit.
gc_collect_cycles()no longer counts indirectly collected strings and resources in its return value. Review assertions or monitoring thresholds built around that number.
Read the full list for the extensions and language features your project uses. Build regression cases from affected application behavior instead of adding tests for every entry in the manual.
5. Define the rollout acceptance checks
Use a short checklist that records both the expected result and evidence:
| Area | Example acceptance check | Evidence to keep |
|---|---|---|
| Login | An existing user’s correct password works; an incorrect one fails. | Authentication test or staging result. |
| Database | A representative read and write complete correctly. | Integration test and relevant logs. |
| Background jobs | A worker processes a job under the intended PHP runtime. | Worker version and job result. |
| Data handling | JSON, date, and serialization behavior matches the application contract. | Regression cases using representative inputs. |
| Operations | Required extensions load and errors are visible. | Platform checks and staging error review. |
These examples are starting points; replace them with your application’s critical paths. Our JSON decoding, password API, and date formatting references can help inspect individual code paths.
Keep the previous runtime artifact, configuration, and lockfile available for rollback. Check whether any accompanying database or dependency change needs its own rollback plan. After rollout, inspect errors and worker behavior before declaring the upgrade complete.
This checklist was reviewed on October 6, 2026. It covers the 8.4 to 8.5 migration and does not claim your application has been tested. If you start on an earlier PHP version, review the intervening migration guides too.