Skip to content

Commit 2dde65c

Browse files
ThomasLandauerThomasLandauer
authored
[Documentation] Events Overview Table: Adding "Passed Argument" column
As announced in #9160 (comment) 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` ;-)
1 parent 176fbed commit 2dde65c

File tree

1 file changed

+48
-42
lines changed

1 file changed

+48
-42
lines changed

‎docs/en/reference/events.rst‎

Lines changed: 48 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -135,38 +135,38 @@ see :ref:`Lifecycle Callbacks<lifecycle-callbacks>`
135135
Events Overview
136136
---------------
137137

138-
+-----------------------------------------------------------------+-----------------------+-----------+
139-
| Event | Dispatched by | Lifecycle |
140-
| | | Callback |
141-
+=================================================================+=======================+===========+
142-
| :ref:`preRemove<reference-events-pre-remove>` | ``$em->remove()`` | Yes |
143-
+-----------------------------------------------------------------+-----------------------+-----------+
144-
| :ref:`postRemove<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
145-
+-----------------------------------------------------------------+-----------------------+-----------+
146-
| :ref:`prePersist<reference-events-pre-persist>` | ``$em->persist()`` | Yes |
147-
| | on *initial* persist | |
148-
+-----------------------------------------------------------------+-----------------------+-----------+
149-
| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
150-
+-----------------------------------------------------------------+-----------------------+-----------+
151-
| :ref:`preUpdate<reference-events-pre-update>` | ``$em->flush()`` | Yes |
152-
+-----------------------------------------------------------------+-----------------------+-----------+
153-
| :ref:`postUpdate<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes |
154-
+-----------------------------------------------------------------+-----------------------+-----------+
155-
| :ref:`postLoad<reference-events-post-load>` | Loading from database | Yes |
156-
+-----------------------------------------------------------------+-----------------------+-----------+
157-
| :ref:`loadClassMetadata<reference-events-load-class-metadata>` | Loading of mapping | No |
158-
| | metadata | |
159-
+-----------------------------------------------------------------+-----------------------+-----------+
160-
| ``onClassMetadataNotFound`` | ``MappingException`` | No |
161-
+-----------------------------------------------------------------+-----------------------+-----------+
162-
| :ref:`preFlush<reference-events-pre-flush>` | ``$em->flush()`` | Yes |
163-
+-----------------------------------------------------------------+-----------------------+-----------+
164-
| :ref:`onFlush<reference-events-on-flush>` | ``$em->flush()`` | No |
165-
+-----------------------------------------------------------------+-----------------------+-----------+
166-
| :ref:`postFlush<reference-events-post-flush>` | ``$em->flush()`` | No |
167-
+-----------------------------------------------------------------+-----------------------+-----------+
168-
| ``onClear`` | ``$em->clear()`` | No |
169-
+-----------------------------------------------------------------+-----------------------+-----------+
138+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
139+
| Event | Dispatched by | Lifecycle | Passed |
140+
| | | Callback | Argument |
141+
+=================================================================+=======================+===========+========================+
142+
| :ref:`preRemove<reference-events-pre-remove>` | ``$em->remove()`` | Yes | |
143+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
144+
| :ref:`postRemove<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | |
145+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
146+
| :ref:`prePersist<reference-events-pre-persist>` | ``$em->persist()`` | Yes | `_LifecycleEventArgs`_ |
147+
| | on *initial* persist | | |
148+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
149+
| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | |
150+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
151+
| :ref:`preUpdate<reference-events-pre-update>` | ``$em->flush()`` | Yes | |
152+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
153+
| :ref:`postUpdate<reference-events-post-update-remove-persist>` | ``$em->flush()`` | Yes | |
154+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
155+
| :ref:`postLoad<reference-events-post-load>` | Loading from database | Yes | |
156+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
157+
| :ref:`loadClassMetadata<reference-events-load-class-metadata>` | Loading of mapping | No | |
158+
| | metadata | | |
159+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
160+
| ``onClassMetadataNotFound`` | ``MappingException`` | No | |
161+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
162+
| :ref:`preFlush<reference-events-pre-flush>` | ``$em->flush()`` | Yes | |
163+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
164+
| :ref:`onFlush<reference-events-on-flush>` | ``$em->flush()`` | No | |
165+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
166+
| :ref:`postFlush<reference-events-post-flush>` | ``$em->flush()`` | No | |
167+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
168+
| ``onClear`` | ``$em->clear()`` | No | |
169+
+-----------------------------------------------------------------+-----------------------+-----------+------------------------+
170170

171171
Naming convention
172172
~~~~~~~~~~~~~~~~~
@@ -296,6 +296,8 @@ specific to a particular entity class's lifecycle.
296296
.. code-block:: attribute
297297
298298
<?php
299+
300+
use Doctrine\Persistence\Event\LifecycleEventArgs;
299301
300302
/**
301303
* #[Entity]
@@ -309,7 +311,7 @@ specific to a particular entity class's lifecycle.
309311
public $value;
310312
311313
#[PrePersist]
312-
public function doStuffOnPrePersist()
314+
public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
313315
{
314316
$this->createdAt = date('Y-m-d H:i:s');
315317
}
@@ -320,15 +322,17 @@ specific to a particular entity class's lifecycle.
320322
$this->value = 'changed from prePersist callback!';
321323
}
322324
323-
#[PostLoad]
324-
public function doStuffOnPostLoad()
325+
#[PreUpdate]
326+
public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs)
325327
{
326-
$this->value = 'changed from postLoad callback!';
328+
$this->value = 'changed from preUpdate callback!';
327329
}
328330
}
329331
.. code-block:: annotation
330332
331333
<?php
334+
335+
use Doctrine\Persistence\Event\LifecycleEventArgs;
332336
333337
/**
334338
* @Entity
@@ -342,7 +346,7 @@ specific to a particular entity class's lifecycle.
342346
public $value;
343347
344348
/** @PrePersist */
345-
public function doStuffOnPrePersist()
349+
public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
346350
{
347351
$this->createdAt = date('Y-m-d H:i:s');
348352
}
@@ -353,10 +357,10 @@ specific to a particular entity class's lifecycle.
353357
$this->value = 'changed from prePersist callback!';
354358
}
355359
356-
/** @PostLoad */
357-
public function doStuffOnPostLoad()
360+
/** @PreUpdate */
361+
public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs)
358362
{
359-
$this->value = 'changed from postLoad callback!';
363+
$this->value = 'changed from preUpdate callback!';
360364
}
361365
}
362366
.. code-block:: xml
@@ -372,7 +376,7 @@ specific to a particular entity class's lifecycle.
372376
<lifecycle-callbacks>
373377
<lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
374378
<lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersist"/>
375-
<lifecycle-callback type="postLoad" method="doStuffOnPostLoad"/>
379+
<lifecycle-callback type="preUpdate" method="doStuffOnPreUpdate"/>
376380
</lifecycle-callbacks>
377381
</entity>
378382
</doctrine-mapping>
@@ -386,7 +390,7 @@ specific to a particular entity class's lifecycle.
386390
type: string(255)
387391
lifecycleCallbacks:
388392
prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
389-
postLoad: [ doStuffOnPostLoad ]
393+
preUpdate: [ doStuffOnPreUpdate ]
390394
391395
Lifecycle Callbacks Event Argument
392396
----------------------------------
@@ -1073,3 +1077,5 @@ and the EntityManager.
10731077
$em = $eventArgs->getEntityManager();
10741078
}
10751079
}
1080+
1081+
.. _LifecycleEventArgs: https://github.com/doctrine/persistence/blob/2.2.x/lib/Doctrine/Persistence/Event/LifecycleEventArgs.php

0 commit comments

Comments
 (0)