improve error message if a migration contains the old base migration class (#1059)

Author: LordSimal

src/Migration/Manager.php

@@ -975,7 +975,8 @@ function ($phpFile) {
 
                     $io->verbose("Loading class <info>$class</info> from <info>$filePath</info>.");
 
-                    // load the migration file
+                    $this->checkMigrationClass($filePath);
+
                     $orig_display_errors_setting = ini_get('display_errors');
                     ini_set('display_errors', 'On');
 
@@ -1025,6 +1026,32 @@ function ($phpFile) {
         return (array)$this->migrations;
     }
 
+    /**
+     * Prevent fatal errors when loading legacy migration files that still reference old classes
+     *
+     * @param string $filePath Migration file path
+     * @return void
+     */
+    protected function checkMigrationClass(string $filePath): void
+    {
+        $contents = file_get_contents($filePath);
+        if ($contents === false) {
+            return;
+        }
+
+        $usesLegacyAbstractMigration =
+            str_contains($contents, 'use Migrations\AbstractMigration;') ||
+            str_contains($contents, 'extends AbstractMigration') ||
+            str_contains($contents, 'extends \Migrations\AbstractMigration');
+
+        if ($usesLegacyAbstractMigration) {
+            throw new RuntimeException(sprintf(
+                'Migration file `%s` uses the legacy `Migrations\\AbstractMigration` class, which is not available in this version. Update the migration to extend `Migrations\\BaseMigration`.',
+                $filePath,
+            ));
+        }
+    }
+
     /**
      * Returns a list of migration files found in the provided migration paths.
      *

tests/TestCase/Migration/ManagerTest.php

@@ -639,6 +639,18 @@ public function testGetMigrationsWithInvalidMigrationClassName()
         $manager->getMigrations();
     }
 
+    public function testGetMigrationsWithLegacyAbstractMigrationClass(): void
+    {
+        $config = new Config(['paths' => ['migrations' => ROOT . '/config/LegacyAbstractMigration']]);
+        $manager = new Manager($config, $this->io);
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessageMatches('/uses the legacy `Migrations\\\\AbstractMigration` class/');
+        $this->expectExceptionMessageMatches('/20260327000000_LegacyAbstractMigration\\.php/');
+
+        $manager->getMigrations();
+    }
+
     public function testGetMigrationsWithAnonymousClass()
     {
         $config = new Config(['paths' => ['migrations' => ROOT . '/config/AnonymousMigrations']]);

tests/test_app/config/LegacyAbstractMigration/20260327000000_LegacyAbstractMigration.php

@@ -0,0 +1,11 @@
+<?php
+declare(strict_types=1);
+
+use Migrations\AbstractMigration;
+
+class LegacyAbstractMigration extends AbstractMigration
+{
+    public function change(): void
+    {
+    }
+}