laminas-migration Tooling Guide (Verified)

This page restates the official Laminas migration tooling workflow for maintainers who need an operational runbook. Source of truth: https://docs.laminas.dev/migration/.

What the tool migrates

• Apps/libraries on Zend Framework v2 or v3 series components
• Apigility (stable)
• Expressive / Expressive components (stable)

ZF1 is a separate modernization problem—see ZF1 center.

Prerequisites

1. Composer ≥ 1.7.0 — composer --version / composer self-update
2. Version control — mandatory; the tool rewrites code, updates composer.json, deletes composer.lock and vendor/

Install (global or clone) — never local project require

composer global require laminas/laminas-migration
# OR clone https://github.com/laminas/laminas-migration.git and composer install there

Do not install laminas/laminas-migration as a local application dependency. Removing vendor/ mid-run can delete the tool and fail the migration.

Migrate command and useful flags

laminas-migration migrate
laminas-migration migrate -e data -e public/images
laminas-migration help migrate

• --exclude / -e — skip heavy directories (caches, images, uploads)
• --filter / -f — regex include filters
• --keep-locked-versions — conservative pins from old lock; Laminas encourages migrating without it; post-clean composer.json and run composer update --lock if you used it

After migrate

git diff
composer install
# run unit + end-to-end tests; exercise critical routes
vendor/bin/phpunit

Look for unexpected renames of your own classes that contained “Zend” in the name, and for configuration key changes that may be app-specific.

// LEGACY
use Zend\Mvc\Application;

// MODERN
use Laminas\Mvc\Application;

--keep-locked-versions post-care

If you migrated conservatively, restore sensible project-level constraints, remove packages that were never direct requirements, then:

composer update --lock

Laminas documentation encourages the non-conservative path to avoid surprises with older Laminas package versions.

Summary

composer global require laminas/laminas-migration
cd some/project
laminas-migration migrate   # often with -e data
composer install
# test

Companion narrative: Migrating Zend Framework to Laminas. From-ZF orientation: From Zend Framework. IDE cutover: PhpStorm.