From e2f4fa2ad45ce8e0edbc77235101d9ab932d58c8 Mon Sep 17 00:00:00 2001
From: Mateusz Charytoniuk <mateusz.charytoniuk@protonmail.com>
Date: Mon, 12 Feb 2024 04:42:55 +0100
Subject: [PATCH] chore: document doctrine events

---
 .../features/database/doctrine/console.md     |  3 +-
 .../features/database/doctrine/entities.md    |  3 +-
 .../database/doctrine/entity-managers.md      |  4 +-
 .../docs/features/database/doctrine/events.md | 87 +++++++++++++++++++
 4 files changed, 94 insertions(+), 3 deletions(-)
 create mode 100644 docs/pages/docs/features/database/doctrine/events.md

diff --git a/docs/pages/docs/features/database/doctrine/console.md b/docs/pages/docs/features/database/doctrine/console.md
index 772ee1b8..fb7d9d9f 100644
--- a/docs/pages/docs/features/database/doctrine/console.md
+++ b/docs/pages/docs/features/database/doctrine/console.md
@@ -1,6 +1,7 @@
 ---
 collections: 
-    - documents
+    - name: documents
+      next: docs/features/database/doctrine/entities
 layout: dm:document
 next: docs/features/database/doctrine/entities
 parent: docs/features/database/doctrine/index
diff --git a/docs/pages/docs/features/database/doctrine/entities.md b/docs/pages/docs/features/database/doctrine/entities.md
index 0b23ce66..d927fb5e 100644
--- a/docs/pages/docs/features/database/doctrine/entities.md
+++ b/docs/pages/docs/features/database/doctrine/entities.md
@@ -1,6 +1,7 @@
 ---
 collections: 
-    - documents
+    - name: documents
+      next: docs/features/database/doctrine/entity-managers
 layout: dm:document
 next: docs/features/database/doctrine/entity-managers
 parent: docs/features/database/doctrine/index
diff --git a/docs/pages/docs/features/database/doctrine/entity-managers.md b/docs/pages/docs/features/database/doctrine/entity-managers.md
index 899da03a..4e2ea6ce 100644
--- a/docs/pages/docs/features/database/doctrine/entity-managers.md
+++ b/docs/pages/docs/features/database/doctrine/entity-managers.md
@@ -1,7 +1,9 @@
 ---
 collections: 
-    - documents
+    - name: documents
+      next: docs/features/database/doctrine/events
 layout: dm:document
+next: docs/features/database/doctrine/events
 parent: docs/features/database/doctrine/index
 title: Entity Managers
 description: >
diff --git a/docs/pages/docs/features/database/doctrine/events.md b/docs/pages/docs/features/database/doctrine/events.md
new file mode 100644
index 00000000..722adf2b
--- /dev/null
+++ b/docs/pages/docs/features/database/doctrine/events.md
@@ -0,0 +1,87 @@
+---
+collections: 
+    - documents
+layout: dm:document
+parent: docs/features/database/doctrine/index
+title: Events
+description: >
+    Learn how to hook into Doctrine's event system.
+---
+
+# Events
+
+You can hook into Doctrine's lifecycle events, including global events and 
+events specific to a particular entity.
+
+# Usage
+
+## Global Doctrine Events
+
+Needs `ListensToDoctrineEvents` attribute. For example:
+
+```php
+<?php
+
+namespace App\DoctrineEventSubscriber;
+
+use Distantmagic\Resonance\Attribute\ListensToDoctrineEvents;
+use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\DoctrineEventSubscriber;
+use Distantmagic\Resonance\SingletonCollection;
+use Doctrine\ORM\Event\LoadClassMetadataEventArgs;
+use Doctrine\ORM\Events;
+
+#[ListensToDoctrineEvents]
+#[Singleton(collection: SingletonCollection::DoctrineEventListener)]
+readonly class AugumentClassMetadata extends DoctrineEventSubscriber
+{
+    public function getSubscribedEvents()
+    {
+        return [
+            Events::loadClassMetadata,
+        ];
+    }
+
+    public function loadClassMetadata(LoadClassMetadataEventArgs $args): void
+    {
+        // augument class metada with something...
+    }
+}
+```
+
+## Entity Listeners
+
+Resonance provides `ListensToDoctrineEntityEvents` attribute that binds the
+listener to the doctrine entity.
+
+Such a class has to be a singleton, added to the `DoctrineEntityListener` 
+collection.
+
+After marking a class with the above attribute, you can add it's methods 
+in a way that is described in 
+[Doctrine's documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/3.0/reference/events.html#entity-listeners-class).
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\DoctrineEntityListener;
+
+use App\DoctrineEntity\MyEntity;
+use Distantmagic\Resonance\Attribute\ListensToDoctrineEntityEvents;
+use Distantmagic\Resonance\Attribute\Singleton;
+use Distantmagic\Resonance\DoctrineEntityListener;
+use Distantmagic\Resonance\Environment;
+use Distantmagic\Resonance\SingletonCollection;
+
+#[ListensToDoctrineEntityEvents(MyEntity::class)]
+#[Singleton(collection: SingletonCollection::DoctrineEntityListener)]
+readonly class SendNewsletterDoubleOptinMail extends DoctrineEntityListener
+{
+    public function postPersist(MyEntity $myEntity): void
+    {
+        // do something with $myEntity...
+    }
+}
+```
-- 
GitLab