feat(2.8): dispatch events (#974)

Author: nikophil

.roave-backward-compatibility-check.xml

@@ -7,5 +7,6 @@
         <ignored-regex>#\[BC\] SKIPPED: Roave\\BetterReflection\\Reflection\\ReflectionClass "Psalm\\Plugin\\PluginEntryPointInterface" could not be found in the located source#</ignored-regex>
         <ignored-regex>#\[BC\] SKIPPED: Roave\\BetterReflection\\Reflection\\ReflectionClass "Psalm\\Plugin\\EventHandler\\AfterMethodCallAnalysisInterface" could not be found in the located source#</ignored-regex>
         <ignored-regex>#(.*)Zenstruck\\Foundry\\Utils\\Rector(.*)#</ignored-regex>
+        <ignored-regex>#(.*)initializeInternal(.*)#</ignored-regex>
     </baseline>
 </roave-bc-check>

composer.json

@@ -40,6 +40,7 @@
         "symfony/browser-kit": "^6.4|^7.0|^8.0",
         "symfony/console": "^6.4|^7.0|^8.0",
         "symfony/dotenv": "^6.4|^7.0|^8.0",
+        "symfony/event-dispatcher": "^6.4|^7.0",
         "symfony/framework-bundle": "^6.4|^7.0|^8.0",
         "symfony/maker-bundle": "^1.55",
         "symfony/phpunit-bridge": "^6.4|^7.0|^8.0",
@@ -83,6 +84,7 @@
     },
     "conflict": {
         "doctrine/persistence": "<2.0",
+        "symfony/event-dispatcher": "<6.4",
         "symfony/framework-bundle": "<6.4"
     },
     "extra": {

config/services.php

@@ -46,6 +46,7 @@
             service('.zenstruck_foundry.in_memory.repository_registry'),
             service('.foundry.persistence.objects_tracker')->nullOnInvalid(),
             param('zenstruck_foundry.enable_auto_refresh_with_lazy_objects'),
+            service('event_dispatcher')->nullOnInvalid(),
         ])
         ->public()
     ;

docs/index.rst

@@ -664,6 +664,57 @@ You can also add hooks directly in your factory class:
 
 Read `Initialization`_ to learn more about the ``initialize()`` method.
 
+Events
+~~~~~~
+
+In addition to hooks, Foundry also leverages `symfony/event-dispatcher` and dispatches events that you can listen to,
+allowing to create hooks globally, as Symfony services:
+
+::
+
+    use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
+    use Zenstruck\Foundry\Object\Event\AfterInstantiate;
+    use Zenstruck\Foundry\Object\Event\BeforeInstantiate;
+    use Zenstruck\Foundry\Persistence\Event\AfterPersist;
+
+    final class FoundryEventListener
+    {
+        #[AsEventListener]
+        public function beforeInstantiate(BeforeInstantiate $event): void
+        {
+            // do something before the object is instantiated:
+            // $event->parameters is what will be used to instantiate the object, manipulate as required
+            // $event->objectClass is the class of the object being instantiated
+            // $event->factory is the factory instance which creates the object
+        }
+
+        #[AsEventListener]
+        public function afterInstantiate(AfterInstantiate $event): void
+        {
+            // $event->object is the instantiated object
+            // $event->parameters contains the attributes used to instantiate the object and any extras
+            // $event->factory is the factory instance which creates the object
+        }
+
+        #[AsEventListener]
+        public function afterPersist(AfterPersist $event): void
+        {
+            // this event is only called if the object was persisted
+            // $event->object is the persisted Post object
+            // $event->parameters contains the attributes used to instantiate the object and any extras
+            // $event->factory is the factory instance which creates the object
+        }
+    }
+
+.. versionadded::  2.8
+
+    Those events are triggered since Foundry 2.8.
+
+.. note::
+
+    If you want to save data to the database in an ``AfterPersist`` listener, Foundry won't flush automatically, and you
+    will need to explicitly call ``EntityManager::flush()`` inside the listener.
+
 Initialization
 ~~~~~~~~~~~~~~
 

src/Configuration.php

@@ -12,6 +12,7 @@
 namespace Zenstruck\Foundry;
 
 use Faker;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Zenstruck\Foundry\Exception\FactoriesTraitNotUsed;
 use Zenstruck\Foundry\Exception\FoundryNotBooted;
 use Zenstruck\Foundry\Exception\PersistenceDisabled;
@@ -63,6 +64,7 @@ public function __construct(
         public readonly ?InMemoryRepositoryRegistry $inMemoryRepositoryRegistry = null,
         public readonly ?PersistedObjectsTracker $persistedObjectsTracker = null,
         private readonly bool $enableAutoRefreshWithLazyObjects = false,
+        private readonly ?EventDispatcherInterface $eventDispatcher = null,
     ) {
         if (null === self::$instance) {
             $this->faker->seed(self::fakerSeed($forcedFakerSeed));
@@ -106,6 +108,16 @@ public function assertPersistenceEnabled(): void
         }
     }
 
+    public function hasEventDispatcher(): bool
+    {
+        return (bool) $this->eventDispatcher;
+    }
+
+    public function eventDispatcher(): EventDispatcherInterface
+    {
+        return $this->eventDispatcher ?? throw new \RuntimeException('No event dispatcher configured.');
+    }
+
     public function inADataProvider(): bool
     {
         return $this->bootedForDataProvider;

src/Object/Event/AfterInstantiate.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Foundry\Object\Event;
+
+use Zenstruck\Foundry\Factory;
+use Zenstruck\Foundry\ObjectFactory;
+
+/**
+ * @author Nicolas PHILIPPE <[email protected]>
+ *
+ * @phpstan-import-type Parameters from Factory
+ */
+final class AfterInstantiate
+{
+    public function __construct(
+        public readonly object $object,
+        /** @phpstan-var Parameters */
+        public readonly array $parameters,
+        /** @var ObjectFactory<object> */
+        public readonly ObjectFactory $factory,
+    ) {
+    }
+}

src/Object/Event/BeforeInstantiate.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Foundry\Object\Event;
+
+use Zenstruck\Foundry\Factory;
+use Zenstruck\Foundry\ObjectFactory;
+
+/**
+ * @author Nicolas PHILIPPE <[email protected]>
+ *
+ * @phpstan-import-type Parameters from Factory
+ */
+final class BeforeInstantiate
+{
+    public function __construct(
+        /** @phpstan-var Parameters */
+        public array $parameters,
+        /** @var class-string */
+        public readonly string $objectClass,
+        /** @var ObjectFactory<object> */
+        public readonly ObjectFactory $factory,
+    ) {
+    }
+}

src/ObjectFactory.php

@@ -11,6 +11,8 @@
 
 namespace Zenstruck\Foundry;
 
+use Zenstruck\Foundry\Object\Event\AfterInstantiate;
+use Zenstruck\Foundry\Object\Event\BeforeInstantiate;
 use Zenstruck\Foundry\Object\Instantiator;
 use Zenstruck\Foundry\Persistence\ProxyGenerator;
 
@@ -205,6 +207,33 @@ final protected function normalizeReusedAttributes(): array
         return $attributes;
     }
 
+    /**
+     * @internal
+     */
+    protected function initializeInternal(): static
+    {
+        if (!Configuration::isBooted() || !Configuration::instance()->hasEventDispatcher()) {
+            return $this;
+        }
+
+        return $this->beforeInstantiate(
+            static function(array $parameters, string $objectClass, self $usedFactory): array {
+                Configuration::instance()->eventDispatcher()->dispatch(
+                    $hook = new BeforeInstantiate($parameters, $objectClass, $usedFactory)
+                );
+
+                return $hook->parameters;
+            }
+        )
+            ->afterInstantiate(
+                static function(object $object, array $parameters, self $usedFactory): void {
+                    Configuration::instance()->eventDispatcher()->dispatch(
+                        new AfterInstantiate($object, $parameters, $usedFactory)
+                    );
+                }
+            );
+    }
+
     /**
      * @return list<object>
      * @internal

src/Persistence/Event/AfterPersist.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Foundry\Persistence\Event;
+
+use Zenstruck\Foundry\Factory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
+
+/**
+ * @author Nicolas PHILIPPE <[email protected]>
+ *
+ * @phpstan-import-type Parameters from Factory
+ */
+final class AfterPersist
+{
+    public function __construct(
+        public readonly object $object,
+        /** @phpstan-var Parameters */
+        public readonly array $parameters,
+        /** @var PersistentObjectFactory<object> */
+        public readonly PersistentObjectFactory $factory,
+    ) {
+    }
+}

src/Persistence/PersistenceManager.php

@@ -35,7 +35,7 @@ final class PersistenceManager
     private bool $flush = true;
     private bool $persist = true;
 
-    /** @var list<callable():void> */
+    /** @var list<callable():bool> */
     private array $afterPersistCallbacks = [];
 
     /**
@@ -79,9 +79,9 @@ public function save(object $object): object
         $om->persist($object);
         $this->flush($om);
 
-        $callbacksCalled = $this->callPostPersistCallbacks();
+        $shouldFlush = $this->callPostPersistCallbacks();
 
-        if ($callbacksCalled) {
+        if ($shouldFlush) {
             $this->flush($om);
         }
 
@@ -96,7 +96,7 @@ public function save(object $object): object
      * @template T of object
      *
      * @param T                     $object
-     * @param list<callable():void> $afterPersistCallbacks
+     * @param list<callable():bool> $afterPersistCallbacks
      *
      * @return T
      */
@@ -445,11 +445,15 @@ private function callPostPersistCallbacks(): bool
         $afterPersistCallbacks = $this->afterPersistCallbacks;
         $this->afterPersistCallbacks = [];
 
+        $shouldFlush = false;
+
         foreach ($afterPersistCallbacks as $afterPersistCallback) {
-            $afterPersistCallback();
+            if ($afterPersistCallback()) {
+                $shouldFlush = true;
+            }
         }
 
-        return true;
+        return $shouldFlush;
     }
 
     /**