From 2dde65c4bacce3c9c26d24fceb9bde938a5ba34c Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 11 Nov 2021 00:22:25 +0100 Subject: [PATCH 1/5] [Documentation] Events Overview Table: Adding "Passed Argument" column As announced in https://github.com/doctrine/orm/pull/9160#issuecomment-954304588 I'm adding the passed "EventArgs" class to the overview table. Once this is complete, my further plan is to remove the entire paragraph https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/events.html#lifecycle-callbacks-event-argument, and probably also the second code block at https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/events.html#entity-listeners-class Is there a better way to link to the source code of `LifecycleEventArgs` than https://github.com/doctrine/persistence/blob/2.2.x/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php ? Also, I changed `postLoad` to `preUpdate` in the code block, to have an example that does not receive `LifecycleEventArgs` ;-) --- docs/en/reference/events.rst | 90 +++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 42 deletions(-) diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index f3e5fe75c38..f4a698566b6 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -135,38 +135,38 @@ see :ref:`Lifecycle Callbacks` Events Overview --------------- -+-----------------------------------------------------------------+-----------------------+-----------+ -| Event | Dispatched by | Lifecycle | -| | | Callback | -+=================================================================+=======================+===========+ -| :ref:`preRemove` | ``$em->remove()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`postRemove` | ``$em->flush()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`prePersist` | ``$em->persist()`` | Yes | -| | on *initial* persist | | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`postPersist` | ``$em->flush()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`preUpdate` | ``$em->flush()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`postUpdate` | ``$em->flush()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`postLoad` | Loading from database | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`loadClassMetadata` | Loading of mapping | No | -| | metadata | | -+-----------------------------------------------------------------+-----------------------+-----------+ -| ``onClassMetadataNotFound`` | ``MappingException`` | No | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`preFlush` | ``$em->flush()`` | Yes | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`onFlush` | ``$em->flush()`` | No | -+-----------------------------------------------------------------+-----------------------+-----------+ -| :ref:`postFlush` | ``$em->flush()`` | No | -+-----------------------------------------------------------------+-----------------------+-----------+ -| ``onClear`` | ``$em->clear()`` | No | -+-----------------------------------------------------------------+-----------------------+-----------+ ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| Event | Dispatched by | Lifecycle | Passed | +| | | Callback | Argument | ++=================================================================+=======================+===========+========================+ +| :ref:`preRemove` | ``$em->remove()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`postRemove` | ``$em->flush()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`prePersist` | ``$em->persist()`` | Yes | `_LifecycleEventArgs`_ | +| | on *initial* persist | | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`postPersist` | ``$em->flush()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`preUpdate` | ``$em->flush()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`postUpdate` | ``$em->flush()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`postLoad` | Loading from database | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`loadClassMetadata` | Loading of mapping | No | | +| | metadata | | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| ``onClassMetadataNotFound`` | ``MappingException`` | No | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`preFlush` | ``$em->flush()`` | Yes | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`onFlush` | ``$em->flush()`` | No | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| :ref:`postFlush` | ``$em->flush()`` | No | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ +| ``onClear`` | ``$em->clear()`` | No | | ++-----------------------------------------------------------------+-----------------------+-----------+------------------------+ Naming convention ~~~~~~~~~~~~~~~~~ @@ -296,6 +296,8 @@ specific to a particular entity class's lifecycle. .. code-block:: attribute createdAt = date('Y-m-d H:i:s'); } @@ -320,15 +322,17 @@ specific to a particular entity class's lifecycle. $this->value = 'changed from prePersist callback!'; } - #[PostLoad] - public function doStuffOnPostLoad() + #[PreUpdate] + public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs) { - $this->value = 'changed from postLoad callback!'; + $this->value = 'changed from preUpdate callback!'; } } .. code-block:: annotation createdAt = date('Y-m-d H:i:s'); } @@ -353,10 +357,10 @@ specific to a particular entity class's lifecycle. $this->value = 'changed from prePersist callback!'; } - /** @PostLoad */ - public function doStuffOnPostLoad() + /** @PreUpdate */ + public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs) { - $this->value = 'changed from postLoad callback!'; + $this->value = 'changed from preUpdate callback!'; } } .. code-block:: xml @@ -372,7 +376,7 @@ specific to a particular entity class's lifecycle. - + @@ -386,7 +390,7 @@ specific to a particular entity class's lifecycle. type: string(255) lifecycleCallbacks: prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ] - postLoad: [ doStuffOnPostLoad ] + preUpdate: [ doStuffOnPreUpdate ] Lifecycle Callbacks Event Argument ---------------------------------- @@ -1073,3 +1077,5 @@ and the EntityManager. $em = $eventArgs->getEntityManager(); } } + +.. _LifecycleEventArgs: https://github.com/doctrine/persistence/blob/2.2.x/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php From 77b7107d05f69c942b9a90a3ee9b60ba6a454bde Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Tue, 23 Nov 2021 01:41:01 +0100 Subject: [PATCH 2/5] Using `const` for `type` --- docs/en/reference/events.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index f4a698566b6..6da07e867d7 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -297,6 +297,7 @@ specific to a particular entity class's lifecycle. Date: Tue, 30 Nov 2021 15:51:20 +0100 Subject: [PATCH 3/5] Completing links to `EventArgs` classes in overview table Questions: 1. Is https://github.com/doctrine/persistence/blob/master/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php correct at all? Shouldn't this be https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/LifecycleEventArgs.php, like all the others? 2. Which one is correct for `preUpdate`? https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/events.html#entity-listeners-class says `PreUpdateEventArgs`, but https://www.doctrine-project.org/projects/doctrine-orm/en/2.10/reference/events.html#listening-and-subscribing-to-lifecycle-events says `LifecycleEventArgs` For the two links to `doctrine/persistence`, I'm linking to `/master/` now, which is being forwarded to `/2.2.x/`. --- docs/en/reference/events.rst | 73 ++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 33 deletions(-) diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index 6da07e867d7..7e3bdfddf3d 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -135,38 +135,38 @@ see :ref:`Lifecycle Callbacks` Events Overview --------------- -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| Event | Dispatched by | Lifecycle | Passed | -| | | Callback | Argument | -+=================================================================+=======================+===========+========================+ -| :ref:`preRemove` | ``$em->remove()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`postRemove` | ``$em->flush()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`prePersist` | ``$em->persist()`` | Yes | `_LifecycleEventArgs`_ | -| | on *initial* persist | | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`postPersist` | ``$em->flush()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`preUpdate` | ``$em->flush()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`postUpdate` | ``$em->flush()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`postLoad` | Loading from database | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`loadClassMetadata` | Loading of mapping | No | | -| | metadata | | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| ``onClassMetadataNotFound`` | ``MappingException`` | No | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`preFlush` | ``$em->flush()`` | Yes | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`onFlush` | ``$em->flush()`` | No | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| :ref:`postFlush` | ``$em->flush()`` | No | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ -| ``onClear`` | ``$em->clear()`` | No | | -+-----------------------------------------------------------------+-----------------------+-----------+------------------------+ ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| Event | Dispatched by | Lifecycle | Passed | +| | | Callback | Argument | ++=================================================================+=======================+===========+=====================================+ +| :ref:`preRemove` | ``$em->remove()`` | Yes | `_LifecycleEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`postRemove` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`prePersist` | ``$em->persist()`` | Yes | `_LifecycleEventArgs`_ | +| | on *initial* persist | | | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`postPersist` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`preUpdate` | ``$em->flush()`` | Yes | `_PreUpdateEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`postUpdate` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`postLoad` | Loading from database | Yes | `_LifecycleEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`loadClassMetadata` | Loading of mapping | No | `_LoadClassMetadataEventArgs` | +| | metadata | | | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| ``onClassMetadataNotFound`` | ``MappingException`` | No | `_OnClassMetadataNotFoundEventArgs` | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`preFlush` | ``$em->flush()`` | Yes | `_PreFlushEventArgs`_ | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`onFlush` | ``$em->flush()`` | No | `_OnFlushEventArgs` | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| :ref:`postFlush` | ``$em->flush()`` | No | `_PostFlushEventArgs` | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ +| ``onClear`` | ``$em->clear()`` | No | `_OnClearEventArgs` | ++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+ Naming convention ~~~~~~~~~~~~~~~~~ @@ -1079,4 +1079,11 @@ and the EntityManager. } } -.. _LifecycleEventArgs: https://github.com/doctrine/persistence/blob/2.2.x/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php +.. _LifecycleEventArgs: https://github.com/doctrine/persistence/blob/master/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php +.. _PreUpdateEventArgs: https://github.com/doctrine/persistence/blob/master/lib/Doctrine/Persistence/Event/PreUpdateEventArgs.php +.. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PreFlushEventArgs.php +.. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PostFlushEventArgs.php +.. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnFlushEventArgs.php +.. _OnClearEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnClearEventArgs.php +.. _LoadClassMetadataEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php +.. _OnClassMetadataNotFoundEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php From 8b6fe52f7417582c222c4bc6109bb60c5dce6608 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 1 Dec 2021 01:01:04 +0100 Subject: [PATCH 4/5] Update events.rst --- docs/en/reference/events.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index 7e3bdfddf3d..d393b7fed06 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -1079,8 +1079,8 @@ and the EntityManager. } } -.. _LifecycleEventArgs: https://github.com/doctrine/persistence/blob/master/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php -.. _PreUpdateEventArgs: https://github.com/doctrine/persistence/blob/master/lib/Doctrine/Persistence/Event/PreUpdateEventArgs.php +.. _LifecycleEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/LifecycleEventArgs.php +.. _PreUpdateEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php .. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PreFlushEventArgs.php .. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PostFlushEventArgs.php .. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnFlushEventArgs.php From 0b0c3e7e5874f4d6f95a08dc995f97be5afa449b Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 9 Dec 2021 12:00:30 +0100 Subject: [PATCH 5/5] Update docs/en/reference/events.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Grégoire Paris --- docs/en/reference/events.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst index d393b7fed06..139f074878d 100644 --- a/docs/en/reference/events.rst +++ b/docs/en/reference/events.rst @@ -1079,11 +1079,11 @@ and the EntityManager. } } -.. _LifecycleEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/LifecycleEventArgs.php -.. _PreUpdateEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php -.. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PreFlushEventArgs.php -.. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/PostFlushEventArgs.php -.. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnFlushEventArgs.php -.. _OnClearEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnClearEventArgs.php -.. _LoadClassMetadataEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php -.. _OnClassMetadataNotFoundEventArgs: https://github.com/doctrine/orm/blob/2.10.x/lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php +.. _LifecycleEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/LifecycleEventArgs.php +.. _PreUpdateEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php +.. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreFlushEventArgs.php +.. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostFlushEventArgs.php +.. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnFlushEventArgs.php +.. _OnClearEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnClearEventArgs.php +.. _LoadClassMetadataEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php +.. _OnClassMetadataNotFoundEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php