Add an optional shouldRun method to migrations. (#55011)

* feat(migrations): shouldRun method on migration classes.

* Add test.

* styleCI fixes

* Formatting change.

* StyleCI

* formatting

* chore: refactor to avoid issues with changing how migrations are loaded

- Refactored where the skip check is done
- Added in a 'SKIPPED' status message for skipped migrations
- Added in a new MigrationResult backed enum to store the new third
'state' of a migration ran.

* fix: add back method

* fix: removed unused method failing tests.

* fix: tests.

* StyleCI

* fix: remove dd()

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: danmatthews

src/Illuminate/Console/View/Components/Task.php

@@ -2,6 +2,7 @@
 
 namespace Illuminate\Console\View\Components;
 
+use Illuminate\Database\Migrations\MigrationResult;
 use Illuminate\Support\InteractsWithTime;
 use Symfony\Component\Console\Output\OutputInterface;
 use Throwable;
@@ -34,10 +35,10 @@ public function render($description, $task = null, $verbosity = OutputInterface:
 
         $startTime = microtime(true);
 
-        $result = false;
+        $result = MigrationResult::Failure;
 
         try {
-            $result = ($task ?: fn () => true)();
+            $result = ($task ?: fn () => MigrationResult::Success)();
         } catch (Throwable $e) {
             throw $e;
         } finally {
@@ -53,7 +54,11 @@ public function render($description, $task = null, $verbosity = OutputInterface:
             $this->output->write("<fg=gray>$runTime</>", false, $verbosity);
 
             $this->output->writeln(
-                $result !== false ? ' <fg=green;options=bold>DONE</>' : ' <fg=red;options=bold>FAIL</>',
+                match ($result) {
+                    MigrationResult::Failure => ' <fg=red;options=bold>FAIL</>',
+                    MigrationResult::Skipped => ' <fg=yellow;options=bold>SKIPPED</>',
+                    default => ' <fg=green;options=bold>DONE</>'
+                },
                 $verbosity,
             );
         }

src/Illuminate/Database/Migrations/Migration.php

@@ -27,4 +27,14 @@ public function getConnection()
     {
         return $this->connection;
     }
+
+    /**
+     * Determine if this migration should run.
+     *
+     * @return bool
+     */
+    public function shouldRun(): bool
+    {
+        return true;
+    }
 }

src/Illuminate/Database/Migrations/MigrationResult.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Illuminate\Database\Migrations;
+
+enum MigrationResult: int
+{
+    case Success = 1;
+    case Failure = 2;
+    case Skipped = 3;
+}

src/Illuminate/Database/Migrations/Migrator.php

@@ -240,12 +240,20 @@ protected function runUp($file, $batch, $pretend)
             return $this->pretendToRun($migration, 'up');
         }
 
-        $this->write(Task::class, $name, fn () => $this->runMigration($migration, 'up'));
+        $shouldRunMigration = $migration instanceof Migration
+            ? $migration->shouldRun()
+            : true;
 
-        // Once we have run a migrations class, we will log that it was run in this
-        // repository so that we don't try to run it next time we do a migration
-        // in the application. A migration repository keeps the migrate order.
-        $this->repository->log($name, $batch);
+        if (! $shouldRunMigration) {
+            $this->write(Task::class, $name, fn () => MigrationResult::Skipped);
+        } else {
+            $this->write(Task::class, $name, fn () => $this->runMigration($migration, 'up'));
+
+            // Once we have run a migrations class, we will log that it was run in this
+            // repository so that we don't try to run it next time we do a migration
+            // in the application. A migration repository keeps the migrate order.
+            $this->repository->log($name, $batch);
+        }
     }
 
     /**

tests/Console/View/ComponentsTest.php

@@ -4,6 +4,7 @@
 
 use Illuminate\Console\OutputStyle;
 use Illuminate\Console\View\Components;
+use Illuminate\Database\Migrations\MigrationResult;
 use Mockery as m;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Console\Output\BufferedOutput;
@@ -108,15 +109,20 @@ public function testTask()
     {
         $output = new BufferedOutput();
 
-        with(new Components\Task($output))->render('My task', fn () => true);
+        with(new Components\Task($output))->render('My task', fn () => MigrationResult::Success);
         $result = $output->fetch();
         $this->assertStringContainsString('My task', $result);
         $this->assertStringContainsString('DONE', $result);
 
-        with(new Components\Task($output))->render('My task', fn () => false);
+        with(new Components\Task($output))->render('My task', fn () => MigrationResult::Failure);
         $result = $output->fetch();
         $this->assertStringContainsString('My task', $result);
         $this->assertStringContainsString('FAIL', $result);
+
+        with(new Components\Task($output))->render('My task', fn () => MigrationResult::Skipped);
+        $result = $output->fetch();
+        $this->assertStringContainsString('My task', $result);
+        $this->assertStringContainsString('SKIPPED', $result);
     }
 
     public function testTwoColumnDetail()

tests/Database/migrations/should_run/2016_01_01_200000_create_flights_table.php

@@ -0,0 +1,36 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateFlightsTable extends Migration
+{
+    public function shouldRun(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::create('flights', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('name');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        Schema::dropIfExists('flights');
+    }
+}

tests/Integration/Migration/MigratorTest.php

@@ -44,6 +44,7 @@ public function testMigrate()
         $this->expectTask('2014_10_12_000000_create_people_table', 'DONE');
         $this->expectTask('2015_10_04_000000_modify_people_table', 'DONE');
         $this->expectTask('2016_10_04_000000_modify_people_table', 'DONE');
+        $this->expectTask('2017_10_04_000000_add_age_to_people', 'SKIPPED');
 
         $this->output->shouldReceive('writeln')->once();
 
@@ -52,6 +53,7 @@ public function testMigrate()
         $this->assertTrue(DB::getSchemaBuilder()->hasTable('people'));
         $this->assertTrue(DB::getSchemaBuilder()->hasColumn('people', 'first_name'));
         $this->assertTrue(DB::getSchemaBuilder()->hasColumn('people', 'last_name'));
+        $this->assertFalse(DB::getSchemaBuilder()->hasColumn('people', 'age'));
     }
 
     public function testMigrateWithoutOutput()
@@ -64,6 +66,7 @@ public function testMigrateWithoutOutput()
         $this->assertTrue(DB::getSchemaBuilder()->hasTable('people'));
         $this->assertTrue(DB::getSchemaBuilder()->hasColumn('people', 'first_name'));
         $this->assertTrue(DB::getSchemaBuilder()->hasColumn('people', 'last_name'));
+        $this->assertFalse(DB::getSchemaBuilder()->hasColumn('people', 'age'));
     }
 
     public function testWithSkippedMigrations()
@@ -120,7 +123,7 @@ public function testPretendMigrate()
         $this->expectTwoColumnDetail('2016_10_04_000000_modify_people_table');
         $this->expectBulletList(['alter table "people" add column "last_name" varchar']);
 
-        $this->output->shouldReceive('writeln')->once();
+        $this->output->shouldReceive('writeln')->times(3);
 
         $this->subject->run([__DIR__.'/fixtures'], ['pretend' => true]);
 

tests/Integration/Migration/fixtures/2017_10_04_000000_add_age_to_people.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function shouldRun(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::table('people', function (Blueprint $table) {
+            $table->unsignedInteger('age')->nullable();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     *
+     * @return void
+     */
+    public function down()
+    {
+        Schema::table('people', function (Blueprint $table) {
+            $table->dropColumn('age');
+        });
+    }
+};