Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Documentation] Events Overview Table: Adding "Passed Argument" column #9184

Merged
merged 5 commits into from
Dec 12, 2021
Merged

[Documentation] Events Overview Table: Adding "Passed Argument" column #9184

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2dde65c
[Documentation] Events Overview Table: Adding "Passed Argument" column
ThomasLandauer Nov 10, 2021
77b7107
Using `const` for `type`
ThomasLandauer Nov 23, 2021
32cd210
Completing links to `EventArgs` classes in overview table
ThomasLandauer Nov 30, 2021
8b6fe52
Update events.rst
ThomasLandauer Dec 1, 2021
0b0c3e7
Update docs/en/reference/events.rst
ThomasLandauer Dec 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 57 additions & 43 deletions docs/en/reference/events.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,38 +135,38 @@ see :ref:`Lifecycle Callbacks<lifecycle-callbacks>`
Events Overview
---------------

+-----------------------------------------------------------------+-----------------------+-----------+
| Event | Dispatched by | Lifecycle |
| | | Callback |
+=================================================================+=======================+===========+
| :ref:`preRemove<reference-events-pre-remove>` | ``$em->remove()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`postRemove<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`prePersist<reference-events-pre-persist>` | ``$em->persist()`` | Yes |
| | on *initial* persist | |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`preUpdate<reference-events-pre-update>` | ``$em->flush()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`postUpdate<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`postLoad<reference-events-post-load>` | Loading from database | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`loadClassMetadata<reference-events-load-class-metadata>` | Loading of mapping | No |
| | metadata | |
+-----------------------------------------------------------------+-----------------------+-----------+
| ``onClassMetadataNotFound`` | ``MappingException`` | No |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`preFlush<reference-events-pre-flush>` | ``$em->flush()`` | Yes |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`onFlush<reference-events-on-flush>` | ``$em->flush()`` | No |
+-----------------------------------------------------------------+-----------------------+-----------+
| :ref:`postFlush<reference-events-post-flush>` | ``$em->flush()`` | No |
+-----------------------------------------------------------------+-----------------------+-----------+
| ``onClear`` | ``$em->clear()`` | No |
+-----------------------------------------------------------------+-----------------------+-----------+
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| Event | Dispatched by | Lifecycle | Passed |
| | | Callback | Argument |
+=================================================================+=======================+===========+=====================================+
| :ref:`preRemove<reference-events-pre-remove>` | ``$em->remove()`` | Yes | `_LifecycleEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`postRemove<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`prePersist<reference-events-pre-persist>` | ``$em->persist()`` | Yes | `_LifecycleEventArgs`_ |
| | on *initial* persist | | |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`preUpdate<reference-events-pre-update>` | ``$em->flush()`` | Yes | `_PreUpdateEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`postUpdate<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | `_LifecycleEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`postLoad<reference-events-post-load>` | Loading from database | Yes | `_LifecycleEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`loadClassMetadata<reference-events-load-class-metadata>` | Loading of mapping | No | `_LoadClassMetadataEventArgs` |
| | metadata | | |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| ``onClassMetadataNotFound`` | ``MappingException`` | No | `_OnClassMetadataNotFoundEventArgs` |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`preFlush<reference-events-pre-flush>` | ``$em->flush()`` | Yes | `_PreFlushEventArgs`_ |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`onFlush<reference-events-on-flush>` | ``$em->flush()`` | No | `_OnFlushEventArgs` |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| :ref:`postFlush<reference-events-post-flush>` | ``$em->flush()`` | No | `_PostFlushEventArgs` |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
| ``onClear`` | ``$em->clear()`` | No | `_OnClearEventArgs` |
+-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+

Naming convention
~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -296,6 +296,9 @@ specific to a particular entity class's lifecycle.
.. code-block:: attribute

<?php

use Doctrine\DBAL\Types\Types;
use Doctrine\Persistence\Event\LifecycleEventArgs;

/**
* #[Entity]
Expand All @@ -305,11 +308,11 @@ specific to a particular entity class's lifecycle.
{
// ...

#[Column(type: 'string', length: 255)]
#[Column(type: Types::STRING, length: 255)]
public $value;

#[PrePersist]
public function doStuffOnPrePersist()
public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
{
$this->createdAt = date('Y-m-d H:i:s');
}
Expand All @@ -320,15 +323,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

<?php

use Doctrine\Persistence\Event\LifecycleEventArgs;

/**
* @Entity
Expand All @@ -342,7 +347,7 @@ specific to a particular entity class's lifecycle.
public $value;

/** @PrePersist */
public function doStuffOnPrePersist()
public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
{
$this->createdAt = date('Y-m-d H:i:s');
}
Expand All @@ -353,10 +358,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
Expand All @@ -372,7 +377,7 @@ specific to a particular entity class's lifecycle.
<lifecycle-callbacks>
<lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
<lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersist"/>
<lifecycle-callback type="postLoad" method="doStuffOnPostLoad"/>
<lifecycle-callback type="preUpdate" method="doStuffOnPreUpdate"/>
</lifecycle-callbacks>
</entity>
</doctrine-mapping>
Expand All @@ -386,7 +391,7 @@ specific to a particular entity class's lifecycle.
type: string(255)
lifecycleCallbacks:
prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
postLoad: [ doStuffOnPostLoad ]
preUpdate: [ doStuffOnPreUpdate ]

Lifecycle Callbacks Event Argument
----------------------------------
Expand Down Expand Up @@ -1073,3 +1078,12 @@ and the EntityManager.
$em = $eventArgs->getEntityManager();
}
}

.. _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