5.next: Capability interfaces for reversible vs directional migrations

[dereuromark]

Refs #1084.

Soft-introduces the capability interfaces proposed in #1084 in the 5.x cycle so the 6.x BC-breaking step lands on top of an already-adopted shape.

What this changes

Two new marker interfaces under the Migrations namespace:

• ReversibleMigrationInterface — for migrations defining a single change() method.
• DirectionalMigrationInterface — for migrations defining separate up() and down() methods.

Method contracts are declared as PHPDoc method tags only (not real abstract methods):

namespace Migrations;

/**
 * @method void change()
 */
interface ReversibleMigrationInterface extends MigrationInterface
{
}

/**
 * @method void up()
 * @method void down()
 */
interface DirectionalMigrationInterface extends MigrationInterface
{
}

Migration\Environment::executeMigration now dispatches via instanceof first and keeps the existing method_exists() fallback for migrations that have not adopted the interfaces yet:

if ($migration instanceof ReversibleMigrationInterface) {
    // change() dispatch (with recording adapter for down)
} elseif ($migration instanceof DirectionalMigrationInterface) {
    $direction === MigrationInterface::UP ? $migration->up() : $migration->down();
} elseif (method_exists($migration, MigrationInterface::CHANGE)) {
    // legacy reversible fallback (5.x only)
} elseif (method_exists($migration, $direction)) {
    // legacy directional fallback (5.x only)
}

Bake templates (skeleton, skeleton-anonymous, diff, snapshot) now emit the matching implements clause for newly generated migrations.

A rector rule (Migrations\Rector\AddMigrationCapabilityInterfaceRector) is shipped for the upgrade — it walks every BaseMigration subclass in a user's config/Migrations folder and adds the right implements clause. Abstract bases and anonymous migration classes are both supported.

A dedicated upgrade guide at docs/en/upgrades/upgrading-to-capability-interfaces.md documents the motivation, per-app before/after examples, the rector-driven upgrade, manual residuals, and the 6.x direction.

Framing note

• Typo detection. A user defining function chnage() still silently no-ops today; once 6.x promotes the PHPDoc method tags to real abstract methods this becomes a static error.
• IDE and static analysis support. Once narrowed via instanceof, IDEs and PHPStan resolve change() / up() / down() directly.
• Semantic clarity. A migration is either reversible or directional. Today both styles are dispatched through the same opaque method_exists lookup.
• Custom runners wrapping MigrationInterface no longer need reflection to figure out the migration style.

Why marker interfaces with PHPDoc method tags only

This is the soft-window shape. Marker interfaces mean:

• No signature is forced on the implementer — implements ReversibleMigrationInterface works even on a migration whose change() has a non-matching signature. Zero BC pressure on existing code.
• Static analyzers and IDEs still resolve the methods via the PHPDoc tags once instanceof narrows the type.
• The 6.x step is mechanical: promote the method tags to real abstract method declarations and drop the method_exists fallback. The BC break in 6.x then only bites users who adopted the interface in 5.x but mistyped the method signature — a much smaller cohort than today's proposal.

Per-app upgrade

For migrations defining change():

use Migrations\BaseMigration;
use Migrations\ReversibleMigrationInterface;

class CreateProducts extends BaseMigration implements ReversibleMigrationInterface
{
    public function change(): void { /* ... */ }
}

For migrations defining up() / down():

use Migrations\BaseMigration;
use Migrations\DirectionalMigrationInterface;

class BackfillOrderTotals extends BaseMigration implements DirectionalMigrationInterface
{
    public function up(): void { /* ... */ }
    public function down(): void { /* ... */ }
}

Or run rector once:

vendor/bin/rector process --config=rector.php

with a rector.php like:

use Migrations\Rector\AddMigrationCapabilityInterfaceRector;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/config/Migrations'])
    ->withRules([AddMigrationCapabilityInterfaceRector::class]);

Full walkthrough including manual residuals (Phinx-style bases, dynamically generated classes, third-party plugins) is in the new upgrade guide.

Forward direction (6.x)

A follow-up 6.x PR will:

• Promote the PHPDoc method tags on both interfaces to real abstract method declarations.
• Remove the method_exists() fallback in Environment.

Apps that ran rector during 5.x see the 6.x bump as a no-op for their migration files.

Notes for reviewers

• The Environment dispatch order is Reversible → Directional → legacy change → legacy up/down. The directional interface check comes before the legacy change fallback so that a class implementing DirectionalMigrationInterface that also defines change() is dispatched via up()/down() — the interface declaration wins over method existence. Test coverage for this in EnvironmentTest::testDirectionalInterfaceWinsOverChangeMethod.
• All 43 comparison fixtures under tests/comparisons/ were regenerated to match the new bake output. No content change beyond the new implements clause and matching use import.
• The PHPDoc method tags on the new interfaces are void returns. The 6.x abstract method declaration should match.
• The rector rule does not run as part of CI — it is upgrade tooling for downstream apps. It does respect abstract bases (so the interface propagates to leaves) and anonymous migration classes.