Download the PHP package w3c/lifecycle-events-bundle without Composer

lifecycle-events-bundle

This Symfony bundle is meant to capture and dispatch events that happen throughout the lifecycle of entities:

• creation
• deletion
• updates

Doctrine already provides such events, but using them directly has a few shortcomings:

• You don't decide at which point in a action you want to dispatch events. Events are fired during a flush.
• When Doctrine events are fired, you are not assured that the entities have actually been saved in the database. This is obvious for preUpdate (sent before persisting the changes), but postPersist and preRemove have the same issue: if you persist two new entities in a single transaction, the first insert could work (thus an event would be sent) but not the second, resulting in no entities being saved at all

This bundle aims at circumventing these issues by providing means to fire entity creation, deletion and update events after a successful flush or whenever needed.

It also provides a set of annotation to configure what events should be sent and when.

This bundle was partially inspired by @kriswallsmith's talk "Matters of State".

Installation

Simply run assuming you have installed composer.phar or composer binary:

Finally, enable the bundle in the kernel:

That's it!

Usage

Annotations

For this bundle to do anything interesting, it is necessary to annotate entities you want to monitor. There are five annotations. Three of them apply to classes (@Create, @Delete and @Update) and the remaining two to properties (@Change, @IgnoreClassUpdates).

All annotations live in the namespace W3C\LifecycleEventsBundle\Annotation, so it is recommended to import it:

@On\Create

Monitors the creation of new entities. It accepts the following parameters:

• event: the event being sent every time an entity is created (w3c.lifecycle.created by default)
• class: the class of this event (W3C\LifecycleEventsBundle\Event\LifecycleEvent by default). This class must have a constructor with the following signature:

@On\Delete

Monitors the deletion (or soft deletion, if you use Doctrine Extensions) of entities. It accepts the following parameters:

• event: the event being sent every time an entity is deleted (w3c.lifecycle.deleted by default)
• class: the class of this event (W3C\LifecycleEventsBundle\Event\LifecycleEvent by default). This class must have a constructor with the following signature:

@On\Update

Monitors updates to entities. It accepts the following parameters:

• event: the event being sent (w3c.lifecycle.updated by default) every time an entity is updated

• class: the class of this event (W3C\LifecycleEventsBundle\Event\LifecycleUpdateEvent by default). This class must have a constructor with the following signature:

• monitor_collections: whether the annotation should monitor changes to collection fields. Defaults to true
• monitor_owning: whether owning side relationship changes should be also monitored as inverse side changes. Defaults to false

@On\Change

Monitors whenever an entity field (property or collection) changes. It accepts the following parameters:

• event: the event being sent (w3c.lifecycle.property_changed or w3c.lifecycle.collection_changed by default) every time an entity is updated
• class: the class of this event (W3C\LifecycleEventsBundle\Event\LifecyclePropertyChangedEvent by default if put on a regular property, W3C\LifecycleEventsBundle\Event\LifecycleCollectionChangedEvent when put on a collection). This class must have a constructor with the following signature for regular properties:

and for collections:

• monitor_owning: whether to record changes to this field when owning sides change (defaults to false). Using @On\Change on inverse side of relationships won't trigger any events unless this paramter is set to true. This parameter is likely to be removed in the next major version and act as if it was set to true since when the annotation is added to the inverse side of relationship, it is obvious it means that you want changes to owning side to be monitored here

@On\IgnoreClassUpdates

This annotation is a bit different. When placed on a field (property or collection), it prevents @On\Update from firing events related to this field. @On\Change ones will still work. This annotation does not allow any parameters.

Example class

With such a class, the following events will be fired:

• PersonEvents::CREATED when a Person is created, with the class PersonEvent
• PersonEvents::DELETED when a Person is deleted, with the class PersonEvent
• PersonEvents::UPDATED when a Person is updated, with the class LifecycleUpdatedEvent, but will not record changes to Person::$friends
• PersonEvents::PROPERTY_CHANGED when Person::$name changes, with the class LifecyclePropertyChangedEvent
• w3c.lifecycle.collection_changed when Person::$friends changes, with the class LifecycleCollectionChangedEvent

Disabling automatic dispatching of events

Lifecycle events are dispatched by default after a successful flush. If needed, this can be disabled:

• globally in config.yml

• temporarily in a container (before Symfony 4):

• temporarily in a container (since Symfony 4):

Events can then be dispatched manually using the following:

Special case: inheritance

If you use inheritance in your entities, make sure to set fields of the parent class(es) protected (or public) so that changes to those can be monitored as belonging to subclasses.

Failing to do so may lead to \ReflectionException exceptions such as:

Even if those fields are not monitored!