README

Migrator is a global CLI tool that analyses the complexity of upgrading or migrating a PHP project. Run it against any codebase to get a scored report across framework coupling, database coupling, dependency compatibility, architecture quality, test coverage, and codebase size.

This is a global tool — do not install it as a project dependency. It runs on your development machine and analyses projects by path.

Requirements

• PHP 8.2+

Installation

Install globally with Composer:

composer global require kerrialn/migrator

Then ensure the global Composer bin directory is in your PATH.

Mac / Linux — add to ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Reload your shell:

source ~/.zshrc

Windows — run in PowerShell (adds permanently for your user):

[System.Environment]::SetEnvironmentVariable(
    "PATH",
    $env:PATH + ";$env:APPDATA\Composer\vendor\bin",
    "User"
)

Then restart your terminal. Alternatively, add %APPDATA%\Composer\vendor\bin via System Properties → Environment Variables.

Usage

Navigate to the project you want to analyse and run:

cd /path/to/your/project
migrator analyse

The tool will prompt you for migration or upgrade mode, then source and target framework or PHP version.

On the first run, create a migrator.php config file in the project root. You can commit this file to persist your configuration.

Configuration

<?php

declare(strict_types=1);

use KerrialNewham\Migrator\Config\Config;

return new Config(
    path: getcwd(),
    exclude: [
        'vendor',
        'tests',
        'node_modules',
        'var',
    ],
);

Options

Mid-migration analysis with legacyDirs

When a project is mid-migration, legacy and new code coexist. Including the legacy directories inflates coupling scores and hides the quality of the new code layer. Use legacyDirs to separate them:

return new Config(
    path: getcwd(),
    exclude: [
        'vendor',
        'tests',
        'node_modules',
        'var',
    ],
    legacyDirs: [
        'addons/main',   // legacy CI3 modules being migrated away
        'system/cms',    // legacy CI3 application layer
    ],
);

The tool will analyse the new code layer independently and append a Legacy Code Remaining section to the report showing:

• Legacy file count vs new code file count
• Migration progress as a percentage of files migrated
• Legacy coupling score with a plain-English label (e.g. heavily coupled — significant rewrite work remains)

Use the pre-migration score (no legacyDirs) as your baseline difficulty rating. Use legacyDirs during migration to track progress.

What it analyses

Upgrade

Scores how difficult it would be to upgrade the project to a newer PHP version:

Scores are rated:

Migration

Scores how difficult it would be to migrate the project to a different framework:

Scores are rated:

Supported frameworks

Detection and coupling analysis is supported for:

• Symfony
• Laravel
• CodeIgniter (CI3 and CI4)
• Yii
• Zend / Laminas
• CakePHP
• Phalcon
• Tempest