Merge branch 'main' into 11.x

Author: Kurt Friars

README.md

@@ -20,11 +20,12 @@ Track and respond to database schema changes in your Laravel application through
 - [Usage](#usage)
   - [Available Events](#available-events)
   - [Event Properties](#event-properties)
+  - [Repository](#repository)
 - [Contributing](#contributing)
 - [Credits](#credits)
 - [License](#license)
 - [Security Vulnerabilities](#security-vulnerabilities)
-- [About Plank](#about-plank)
+- [About Plank](#check-us-out)
 
 ## Installation
 
@@ -114,11 +115,13 @@ The package provides four main events:
 ### Event Properties
 
 Each event includes basic connection information:
+
 - `connection` - The name of the database connection
 - `databaseName` - The name of the database
 - `driverName` - The database driver being used
 
 #### TableCreated Event
+
 ```php
 public readonly string $table;
 public readonly Collection $columns;      // Added columns
@@ -127,6 +130,7 @@ public readonly Collection $foreignKeys;  // Added foreign keys
 ```
 
 #### TableChanged Event
+
 ```php
 public readonly string $table;
 public readonly Collection $addedColumns;
@@ -141,16 +145,50 @@ public readonly Collection $droppedForeignKeys;
 ```
 
 #### TableDropped Event
+
 ```php
 public readonly string $table;
 ```
 
 #### TableRenamed Event
+
 ```php
 public readonly string $from;
 public readonly string $to;
 ```
 
+### Repository
+
+The event repository collects the schema events that occur during the migrations which can be retrieved after the `MigrationsEnded` event is fired by the Migrator.
+
+If your application wants to handle dispatching and flushing the events, you can set the `schema-events.listeners.finished` listener to `null` and listen to the `MigrationsEnded` event in your application.
+
+The schema event repository can be controlled using the `SchemaEvents` facade.
+
+#### get()
+
+Retrieve all schema events that were fired during the course of the migrations.
+
+#### created()
+
+Retrieve all `TableCreated` events that were fired during the course of the migrations.
+
+#### changed()
+
+Retrieve all `TableChanged` events that were fired during the course of the migrations.
+
+#### renamed()
+
+Retrieve all `TableRenamed` events that were fired during the course of the migrations.
+
+#### dropped()
+
+Retrieve all `TableDropped` events that were fired during the course of the migrations.
+
+#### flush()
+
+Clear all schema events stored in the schema event repository.
+
 ## Contributing
 
 Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

config/schema-events.php

@@ -10,15 +10,14 @@
     |--------------------------------------------------------------------------
     |
     | `ran`:
-    | This listens to `MigrationStarted` events and bubbles up some more granular
-    | events based on the changes taking place to the schema.
-    |
-    | If the `finished` listener is not configured, these events will bubble up
-    | immediately.
+    | This listens to `MigrationStarted` event which is dispatched before each
+    | migration file is run. This listener is responsible for collecting the
+    | schema events that will be occurring during the run.
     |
     | `finished`:
-    | This listens for the completion of migrations being run and batches the more
-    | granular events parsed during `ran` into one larger event to be processed.
+    | This listens for the completion of migrations being run and emits all
+    | of the collected schema events. If this is
+    |
     */
     'listeners' => [
         'ran' => MigrationRan::class,

src/Facades/SchemaEvents.php

@@ -11,8 +11,13 @@
 use Plank\LaravelSchemaEvents\Repository\EventRepository;
 
 /**
- * @method static void store(Collection<TableCreated|TableChanged|TableDropped|TableRenamed> $events)
  * @method static Collection<TableCreated|TableChanged|TableDropped|TableRenamed> get()
+ * @method static Collection<TableCreated> created()
+ * @method static Collection<TableChanged> changed()
+ * @method static Collection<TableDropped> dropped()
+ * @method static Collection<TableRenamed> renamed()
+ * @method static void flush()
+ * @method static void store(Collection<TableCreated|TableChanged|TableDropped|TableRenamed> $events)
  */
 class SchemaEvents extends Facade
 {

src/Listeners/MigrationsFinished.php

@@ -12,5 +12,7 @@ public function handle(MigrationsEnded $event)
     {
         SchemaEvents::get()
             ->each(fn ($event) => Event::dispatch($event));
+
+        SchemaEvents::flush();
     }
 }

src/Repository/EventRepository.php

@@ -3,6 +3,10 @@
 namespace Plank\LaravelSchemaEvents\Repository;
 
 use Illuminate\Support\Collection;
+use Plank\LaravelSchemaEvents\Events\TableChanged;
+use Plank\LaravelSchemaEvents\Events\TableCreated;
+use Plank\LaravelSchemaEvents\Events\TableDropped;
+use Plank\LaravelSchemaEvents\Events\TableRenamed;
 
 class EventRepository
 {
@@ -13,17 +17,56 @@ public function __construct()
         $this->events = new Collection;
     }
 
-    public function get()
+    /**
+     * @return Collection<TableCreated|TableChanged|TableDropped|TableRenamed>
+     */
+    public function get(): Collection
     {
-        $events = $this->events;
+        return $this->events;
+    }
 
-        $this->events = new Collection;
+    /**
+     * @return Collection<TableCreated>
+     */
+    public function created(): Collection
+    {
+        return $this->events->filter(fn ($event) => $event instanceof TableCreated)->values();
+    }
 
-        return $events;
+    /**
+     * @return Collection<TableChanged>
+     */
+    public function changed(): Collection
+    {
+        return $this->events->filter(fn ($event) => $event instanceof TableChanged)->values();
+    }
+
+    /**
+     * @return Collection<TableDropped>
+     */
+    public function dropped(): Collection
+    {
+        return $this->events->filter(fn ($event) => $event instanceof TableDropped)->values();
     }
 
-    public function store(Collection $events)
+    /**
+     * @return Collection<TableRenamed>
+     */
+    public function renamed(): Collection
+    {
+        return $this->events->filter(fn ($event) => $event instanceof TableRenamed)->values();
+    }
+
+    /**
+     * @param  Collection<TableCreated|TableChanged|TableDropped|TableRenamed>  $events
+     */
+    public function store(Collection $events): void
     {
         $this->events = $this->events->concat($events);
     }
+
+    public function flush(): void
+    {
+        $this->events = new Collection;
+    }
 }

tests/Feature/EventRepositoryTest.php

@@ -0,0 +1,25 @@
+<?php
+
+use Illuminate\Database\Events\MigrationsEnded;
+use Illuminate\Support\Facades\Event;
+use Plank\LaravelSchemaEvents\Facades\SchemaEvents;
+
+use function Pest\Laravel\artisan;
+
+it('events are collected and queried correctly', function () {
+    Event::forget(MigrationsEnded::class);
+
+    artisan('migrate', [
+        '--path' => migrationPath('repository'),
+        '--realpath' => true,
+    ])->run();
+
+    expect(SchemaEvents::get())->toHaveCount(4);
+    expect(SchemaEvents::created())->toHaveCount(1);
+    expect(SchemaEvents::changed())->toHaveCount(1);
+    expect(SchemaEvents::renamed())->toHaveCount(1);
+    expect(SchemaEvents::dropped())->toHaveCount(1);
+
+    SchemaEvents::flush();
+    expect(SchemaEvents::get())->toBeEmpty();
+});

tests/Migrations/repository/2025_02_13_000002_create_comments_table.php

@@ -0,0 +1,23 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::create('comments', function (Blueprint $table) {
+            $table->id();
+            $table->unsignedBigInteger('post_id');
+            $table->string('body');
+            $table->timestamps();
+
+            $table->foreign('post_id')
+                ->references('id')
+                ->on('posts')
+                ->nullOnDelete();
+        });
+    }
+};

tests/Migrations/repository/2025_02_13_000003_alter_posts_table.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::table('posts', function (Blueprint $table) {
+            $table->string('subtitle')->after('title');
+            $table->string('slug')->after('subtitle');
+            $table->unique('slug');
+            $table->longText('body')->change();
+            $table->foreignId('publisher_id')->constrained();
+            $table->string('published_at');
+            $table->index(['published_at']);
+
+            $table->renameColumn('description', 'blurb');
+            $table->dropColumn('teaser');
+            $table->dropForeign(['author_id']);
+            $table->dropIndex(['tag']);
+            $table->renameIndex('posts_category_index', 'category_index');
+        });
+    }
+};

tests/Migrations/repository/2025_02_13_000004_rename_posts_table.php

@@ -0,0 +1,12 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::rename('posts', 'articles');
+    }
+};

tests/Migrations/repository/2025_02_13_000005_drop_posts_table.php

@@ -0,0 +1,12 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::drop('articles');
+    }
+};