PHP Migration Checklist — 30 Points Before Deployment [2026]

A PHP migration checklist turns "we will rewrite the code for a newer version" into a predictable process with clear steps and decision points. Below are 30 items across five phases — from inventory to post-deployment monitoring — together with how to verify each one. You can use it as a migration plan template or as an inspection tool if someone else is running the migration.

Key takeaway: The order of phases matters: first measure (audit), then protect (tests), then rewrite (Rector), then deploy (staging → production), and finally observe (monitoring). Every phase ends with an acceptance criterion — without meeting it, you do not move on.

Phase 1 — Inventory and compatibility audit

• Goal: know exactly what will stop working on the target PHP version. Acceptance criterion: a blocker list split into "automatic", "manual" and "library replacement" items.

• 1. Write down environment versions — PHP (target and current), framework/platform version, database version. php -v, composer show, hosting panel.

• 2. Run PHPCompatibility — a scan for removed and changed constructs: vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4-.

• 3. Run PHPStan at level 5 — it catches type and call problems that become errors in the new version.

• 4. Review dependencies — composer outdated and composer why-not php 8.4: which packages support the target version and which are abandoned.

• 5. List PHP extensions — the extensions in use (php -m) and a check that all exist in the target version (e.g. mysql_* → mysqli/PDO).

• 6. Identify generated code — template caches, ORM-generated files, vendor code: exclude them from the migration so you do not "fix" files that get overwritten.

• Acceptance criterion: a document with the blocker list and a first effort estimate. That document is the migration plan — without it the later phases are guesswork.

Phase 2 — Protection with tests

• Goal: a safety net to verify mass changes. Acceptance criterion: critical-path tests passing on the current PHP version.

• 7. Choose critical paths — login, registration, checkout, payment, document generation, the most important integrations. Usually 5–8 flows.

• 8. Write characterization tests — tests that lock in current behavior (bugs included). In old code, do not test "how it should be", test "how it is".

• 9. Prepare test data — a copy of the production database (anonymized) or realistic fixtures. A migration against an empty database will not reveal problems.

• 10. Run the tests on the current version — a green starting point is a condition. If tests fail before the migration, they will fail after it.

• 11. Add the tests to CI (if you have one) — tests must run automatically on every commit, on both PHP versions (current and target).

• Acceptance criterion: a test suite covering the critical paths, runnable with a single command.

Phase 3 — Refactoring and fixes

• Goal: code compatible with the target PHP version, changes split into readable steps. Acceptance criterion: green tests and clean PHPStan on the target version.

• 12. Configure Rector — a rector.php file with withPhpSets for the target version and paths to code and tests.

• 13. Run Rector in preview mode — --dry-run, review the scope of changes (it can be thousands of lines).

• 14. Apply changes one version step at a time — for large projects: 7.4 → 8.0 separately, 8.0 → 8.1 separately, etc. One commit per step.

• 15. Run the tests after every step — a regression after one step is easy to roll back; after five steps at once, it is hard.

• 16. Fix by hand what the machines could not — logic depending on changed behavior (casting, sorting, numeric string comparisons).

• 17. Replace abandoned libraries — each replacement is a separate task with its own test; plan them from the Phase 1 audit.

• 18. Format the code — PHP-CS-Fixer or Pint after mass changes, so the diffs stay readable for the team.

• 19. Clear deprecation warnings to zero — run the application on the target version and bring the logs to zero warnings. Leftover deprecations are a to-do list that will not disappear by itself.

• Acceptance criterion: the migration branch passes tests and PHPStan on the target PHP version, logs free of deprecations.

Phase 4 — Staging and deployment

• Goal: confirmed compatibility on an environment mirroring production. Acceptance criterion: staging runs stable on the target version, rollback plan ready.

• 20. Build staging on the target PHP version — with the same extensions and configuration (php.ini, OPcache) as production.

• 21. Load a copy of production data — including integrations: API keys in test mode, webhooks disabled or redirected.

• 22. Walk the manual critical-path tests — automated tests do not cover everything a human sees (visual defects, form edge cases).

• 23. Check external integrations — payments, couriers, marketplaces, ERP: a full test transaction on every channel.

• 24. Prepare the rollback plan — the old PHP version stays on the server; you know how to return in 5 minutes (version switch + possible code rollback).

• 25. Schedule the deployment window — outside peak traffic, with someone available afterwards. Deploying on Friday afternoon is an anti-pattern.

• 26. Deploy and watch live — error logs, response times, queues, payments. The first 24–48 hours are the period of highest vigilance.

• Acceptance criterion: production on the target PHP version, key metrics unchanged or better, no new errors in the logs.

Phase 5 — Stabilization and clean-up

• Goal: close the migration and prepare the ground for the next one. Acceptance criterion: the system stable for 2–4 weeks, the technical backlog list updated.

• 27. Watch the logs for 2–4 weeks — deprecations, slow queries, integration errors. New warnings usually mark places the tests did not cover.

• 28. Upgrade dependencies and the framework — the second phase of the migration: once PHP is stable, raise the libraries and the framework to target versions.

• 29. Add Rector to CI — a rector process --dry-run step in the pipeline blocks old patterns from returning in new code.

• 30. Plan the next upgrade — note the EOL date of the target version (e.g. 8.4 → 31.12.2028) and schedule the next migration a year before it.

• Acceptance criterion: the migration closed, the system on a supported version, the next step planned well in advance.

The most common mistakes this checklist eliminates

Experience shows the same missteps across projects.

• Starting without an audit — "we will just fix the errors as they pop up". The result: the migration drags on for weeks as blockers surface one by one.
• Jumping across all versions at once — without intermediate steps you cannot attribute a regression to a change. Diagnosis takes days instead of hours.
• No tests and "clicking through by hand" — manual verification covers 10% of the surface. The rest surfaces in front of users.
• Staging different from production — different extensions, different php.ini, no OPcache. "It works on my machine" right before a production failure.
• Deploying without a rollback plan — the first serious error with no way back means downtime counted in hours.
• Forgotten dependencies — a PHP migration without library upgrades is half the work; an old library on new PHP usually does not work better.

The full process — each stage described with tools and costs — is in the PHP migration guide. Working with Rector in practice is covered in the Rector PHP upgrade guide, and the budget ranges in the article on the PHP migration cost. If your system runs on 8.2, check the deadline in the PHP 8.2 end of life article.

Frequently asked questions

Does the PHP migration checklist work for small projects?

Yes — in small projects some items take minutes (inventory, audit) and the whole thing closes within days. Scale the depth, do not skip phases: even in a small project the order "measure → protect → rewrite → deploy → observe" prevents costly surprises.

How many checklist items need a developer, and how many can I do myself?

The inventory (1, 5), backups and part of the manual verification (22, 23) you can do yourself. The compatibility audit, refactoring, tests and deployment need a developer. If a contractor runs the migration, the checklist is your inspection tool — ask about the status of each phase and its acceptance criterion.

When should I start a migration according to this checklist?

Count backwards from the EOL date: for PHP 8.2 (EOL 31.12.2026) start no later than October–November to leave a buffer for unexpected blockers. General rule: start planning a year before your current version's EOL, and execution — six months before.

What if I find more blockers during the migration than the audit showed?

That is normal in undocumented projects — an audit covers most, not everything. Treat new blockers as plan items: add them to the list, estimate the effort, decide (fix vs replace vs cut the feature). That is exactly why the rollout is planned with a time buffer rather than "down to the wire" with EOL.

Does a PHP migration require a database migration?

Usually not — changing the PHP version does not require database changes. Exceptions: abandoned ORM libraries may require schema updates, and code using removed database APIs (e.g. mysql_*) must be rewritten for PDO/mysqli. A database server migration (e.g. MySQL 5.7 → 8.0) is a separate project — plan it deliberately, not "along the way".

How should the completed migration be documented?

• Minimum: starting and target PHP versions, the list of replaced libraries, the scope of code changes (links to commits), test results, the deployment date and post-deployment observations. The document will be useful for the next migration — and for security audits, which increasingly ask about the update history.

Sources

• PHP.net — supported versions
• PHP.net — migration guides between versions
• Rector — automated refactoring
• PHPCompatibility — compatibility scan
• PHPStan — static analysis