diff --git a/src/Migration/Manager.php b/src/Migration/Manager.php
index 4a9f1886..6baad31e 100644
--- a/src/Migration/Manager.php
+++ b/src/Migration/Manager.php
@@ -975,7 +975,8 @@ function ($phpFile) {
$io->verbose("Loading class $class from $filePath.");
- // 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.
*
diff --git a/tests/TestCase/Migration/ManagerTest.php b/tests/TestCase/Migration/ManagerTest.php
index ba7c324d..4efcf70c 100644
--- a/tests/TestCase/Migration/ManagerTest.php
+++ b/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']]);
diff --git a/tests/test_app/config/LegacyAbstractMigration/20260327000000_LegacyAbstractMigration.php b/tests/test_app/config/LegacyAbstractMigration/20260327000000_LegacyAbstractMigration.php
new file mode 100644
index 00000000..c7e43eb8
--- /dev/null
+++ b/tests/test_app/config/LegacyAbstractMigration/20260327000000_LegacyAbstractMigration.php
@@ -0,0 +1,11 @@
+