[12.x] Fix support for adding custom observable events from traits (#55286)

* Add failing test

* Resolve observer attributes after booting has finished

- This ensure that all custom events have been registered by any traits first.
- It also prevents a new instance of the model from being created by the call to `observe` too early, since an instance created before booting has finished would be in an inconsistent state due to not all of the trait boot methods being run yet and not all of the initializer methods would be registered yet, so they would not be run either.

* Style fixes

* Add tests for booted callbacks

* Add `whenBooted` method to models

* Use `whenBooted` instead of registering an event listener

- This removes any reliance on the event dispatcher, which complicated testing.

* Clear the callbacks when clearing booted models

* formatting

---------

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

Author: willrowe

src/Illuminate/Database/Eloquent/Concerns/HasEvents.php

@@ -38,7 +38,7 @@ trait HasEvents
      */
     public static function bootHasEvents()
     {
-        static::observe(static::resolveObserveAttributes());
+        static::whenBooted(fn () => static::observe(static::resolveObserveAttributes()));
     }
 
     /**

src/Illuminate/Database/Eloquent/Model.php

@@ -3,6 +3,7 @@
 namespace Illuminate\Database\Eloquent;
 
 use ArrayAccess;
+use Closure;
 use Illuminate\Contracts\Broadcasting\HasBroadcastChannel;
 use Illuminate\Contracts\Queue\QueueableCollection;
 use Illuminate\Contracts\Queue\QueueableEntity;
@@ -149,6 +150,13 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
      */
     protected static $booted = [];
 
+    /**
+     * The callbacks that should be executed after the model has booted.
+     *
+     * @var array
+     */
+    protected static $bootedCallbacks = [];
+
     /**
      * The array of trait initializers that will be called on each new instance.
      *
@@ -279,6 +287,12 @@ protected function bootIfNotBooted()
             static::boot();
             static::booted();
 
+            static::$bootedCallbacks[static::class] ??= [];
+
+            foreach (static::$bootedCallbacks[static::class] as $callback) {
+                $callback();
+            }
+
             $this->fireModelEvent('booted', false);
         }
     }
@@ -357,6 +371,19 @@ protected static function booted()
         //
     }
 
+    /**
+     * Register a closure to be executed after the model has booted.
+     *
+     * @param  \Closure  $callback
+     * @return void
+     */
+    protected static function whenBooted(Closure $callback)
+    {
+        static::$bootedCallbacks[static::class] ??= [];
+
+        static::$bootedCallbacks[static::class][] = $callback;
+    }
+
     /**
      * Clear the list of booted models so they will be re-booted.
      *
@@ -365,6 +392,7 @@ protected static function booted()
     public static function clearBootedModels()
     {
         static::$booted = [];
+        static::$bootedCallbacks = [];
 
         static::$globalScopes = [];
     }

tests/Database/DatabaseEloquentModelTest.php

@@ -2293,6 +2293,35 @@ public function testModelIsBootedOnUnserialize()
         $this->assertTrue(EloquentModelBootingTestStub::isBooted());
     }
 
+    public function testCallbacksCanBeRunAfterBootingHasFinished()
+    {
+        $this->assertFalse(EloquentModelBootingCallbackTestStub::$bootHasFinished);
+
+        $model = new EloquentModelBootingCallbackTestStub();
+
+        $this->assertTrue($model::$bootHasFinished);
+
+        EloquentModelBootingCallbackTestStub::unboot();
+    }
+
+    public function testBootedCallbacksAreSeparatedByClass()
+    {
+        $this->assertFalse(EloquentModelBootingCallbackTestStub::$bootHasFinished);
+
+        $model = new EloquentModelBootingCallbackTestStub();
+
+        $this->assertTrue($model::$bootHasFinished);
+
+        $this->assertFalse(EloquentChildModelBootingCallbackTestStub::$bootHasFinished);
+
+        $model = new EloquentChildModelBootingCallbackTestStub();
+
+        $this->assertTrue($model::$bootHasFinished);
+
+        EloquentModelBootingCallbackTestStub::unboot();
+        EloquentChildModelBootingCallbackTestStub::unboot();
+    }
+
     public function testModelsTraitIsInitialized()
     {
         $model = new EloquentModelStubWithTrait;
@@ -3602,6 +3631,7 @@ class EloquentModelBootingTestStub extends Model
     public static function unboot()
     {
         unset(static::$booted[static::class]);
+        unset(static::$bootedCallbacks[static::class]);
     }
 
     public static function isBooted()
@@ -4121,3 +4151,30 @@ class EloquentModelWithUseFactoryAttribute extends Model
 {
     use HasFactory;
 }
+
+trait EloquentTraitBootingCallbackTestStub
+{
+    public static function bootEloquentTraitBootingCallbackTestStub()
+    {
+        static::whenBooted(fn () => static::$bootHasFinished = true);
+    }
+}
+
+class EloquentModelBootingCallbackTestStub extends Model
+{
+    use EloquentTraitBootingCallbackTestStub;
+
+    public static bool $bootHasFinished = false;
+
+    public static function unboot()
+    {
+        unset(static::$booted[static::class]);
+        unset(static::$bootedCallbacks[static::class]);
+        static::$bootHasFinished = false;
+    }
+}
+
+class EloquentChildModelBootingCallbackTestStub extends EloquentModelBootingCallbackTestStub
+{
+    public static bool $bootHasFinished = false;
+}

tests/Integration/Database/EloquentModelCustomEventsTest.php

@@ -2,6 +2,7 @@
 
 namespace Illuminate\Tests\Integration\Database\EloquentModelCustomEventsTest;
 
+use Illuminate\Database\Eloquent\Attributes\ObservedBy;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Schema\Blueprint;
 use Illuminate\Support\Facades\Event;
@@ -24,6 +25,11 @@ protected function afterRefreshingDatabase()
         Schema::create('test_model1', function (Blueprint $table) {
             $table->increments('id');
         });
+
+        Schema::create('eloquent_model_stub_with_custom_event_from_traits', function (Blueprint $table) {
+            $table->boolean('custom_attribute');
+            $table->boolean('observer_attribute');
+        });
     }
 
     public function testFlushListenersClearsCustomEvents()
@@ -45,6 +51,19 @@ public function testCustomEventListenersAreFired()
 
         $this->assertTrue($_SERVER['fired_event']);
     }
+
+    public function testAddObservableEventFromTrait()
+    {
+        $model = new EloquentModelStubWithCustomEventFromTrait();
+
+        $this->assertNull($model->custom_attribute);
+        $this->assertNull($model->observer_attribute);
+
+        $model->completeCustomAction();
+
+        $this->assertTrue($model->custom_attribute);
+        $this->assertTrue($model->observer_attribute);
+    }
 }
 
 class TestModel1 extends Model
@@ -59,3 +78,36 @@ class CustomEvent
 {
     //
 }
+
+trait CustomEventTrait
+{
+    public function completeCustomAction()
+    {
+        $this->custom_attribute = true;
+
+        $this->fireModelEvent('customEvent');
+    }
+
+    public function initializeCustomEventTrait()
+    {
+        $this->addObservableEvents([
+            'customEvent',
+        ]);
+    }
+}
+
+class CustomObserver
+{
+    public function customEvent(EloquentModelStubWithCustomEventFromTrait $model)
+    {
+        $model->observer_attribute = true;
+    }
+}
+
+#[ObservedBy(CustomObserver::class)]
+class EloquentModelStubWithCustomEventFromTrait extends Model
+{
+    use CustomEventTrait;
+
+    public $timestamps = false;
+}