From 6f223643388911d381f196e844b704387e00f21f Mon Sep 17 00:00:00 2001 From: Maxime Veber Date: Mon, 29 Jul 2024 11:36:34 +0200 Subject: [PATCH] :memo: Improve doc for v3 --- CHANGELOG.md | 4 +++ README.md | 29 +++++++++++++++++----- composer.json | 2 +- docs/domain_event_dispatcher.md | 34 +++++++++++++------------- docs/injection_in_doctrine_entities.md | 16 +++--------- 5 files changed, 49 insertions(+), 36 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8d0bb3..0a62b99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Changed + +- New way of injecting the dispatcher to entities. This is great and also supports proxies! (which was previously a limitation) + ## [2.3.3] - 2023-05-16 ### Added diff --git a/README.md b/README.md index a829ae3..8e1eb10 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,21 @@ As your model needs a dispatcher you need to call the `setDispatcher()` method a > It doesn't use the constructor to add the dispatcher because in PHP you can create objects without the constructor. For instance, that's what Doctrine does. +```php +use Biig\Component\Domain\Model\Instantiator\Instantiator; +use Doctrine\ORM\EntityManager; + +class SomeController +{ + public function index(Instantiator $instantiator, EntityManager $entityManager) + { + $model = $instantiator->instantiate(YourModel::class); + $entityManager->persist($model); + $entityManager->flush(); + } +} +``` + Integration to Symfony ---------------------- @@ -98,10 +113,12 @@ Learn more about [Symfony Integration](/docs/domain_event_dispatcher.md#symfony- Versions -------- -| Version | Status | Documentation | Symfony Version | PHP Version | -|---------|------------|---------------| --------------- | ------------| -| 1.x | Maintained | [v1][v1-doc] | '>= 3.3 && <5' | '>= 7.1' | -| 2.x | Latest | [v2][v2-doc] | '>= 4.3' | '>= 7.1' | +| Version | Status | Documentation | Symfony Version | PHP Version | +|---------|------------|----------------|-----------------|-------------| +| 1.x | Deprecated | [v1][v1-doc] | >= 3.3 && <5 | >= 7.1 | +| 2.x | Maintained | [v2][v2-doc] | >= 4.3 | >= 7.4 | +| 3.x | Latest | [v3][v3-doc] | >= 5.4 | >= 8.1 | -[v1-doc]: https://github.com/biig-io/DomainComponent/tree/v1 -[v2-doc]: https://github.com/biig-io/DomainComponent +[v1-doc]: https://github.com/swagindustries/doctrine-domain-events/tree/v1.5.2/docs +[v2-doc]: https://github.com/swagindustries/doctrine-domain-events/tree/v2.3.3/docs +[v3-docs]: https://github.com/swagindustries/doctrine-domain-events/tree/master/docs diff --git a/composer.json b/composer.json index 5518a93..4ab37e7 100644 --- a/composer.json +++ b/composer.json @@ -4,7 +4,7 @@ "license": "MIT", "require": { "php": ">=8.1", - "symfony/event-dispatcher": "^5.0|^6.0|^7.0", + "symfony/event-dispatcher": "^5.4|^6.0|^7.0", "doctrine/doctrine-bundle": "^1.8|^2.0", "doctrine/orm": "^2.18.3" }, diff --git a/docs/domain_event_dispatcher.md b/docs/domain_event_dispatcher.md index c930bd4..b942564 100644 --- a/docs/domain_event_dispatcher.md +++ b/docs/domain_event_dispatcher.md @@ -8,7 +8,7 @@ domain events. Make a rule ----------- -To make a new rule (its a listener) you should implement the `DomainRuleInterface`. +To make a new rule (it's a listener) you should implement the `DomainRuleInterface`. ### Standalone usage @@ -20,11 +20,13 @@ use Biig\Component\Domain\Rule\DomainRuleInterface; use Biig\Component\Domain\Event\DomainEvent; $dispatcher->addRule(new class implements DomainRuleInterface { - public function execute(DomainEvent $event) { + public function execute(DomainEvent $event) + { // add some specific behavior } - public function on() { + public function on() + { return 'on.event'; } }); @@ -32,7 +34,8 @@ $dispatcher->addRule(new class implements DomainRuleInterface { #### Add a post persist delayed rule -A post persist rule will occure only if the specified event is emit, but only after the data is persisted in storage. Basically flushed in the case of Doctrine. +A post persist rule will occur only if the specified event is emitted, but only after the data is persisted in storage. +Basically flushed in the case of Doctrine. ```php addRule(new class implements PostPersistDomainRuleInterface { - public function execute(DomainEvent $event) { + public function execute(DomainEvent $event) + { // add some specific behavior } - public function after() { - return 'on.event'; // You have to specify the model + public function after() + { + return 'on.event'; } }); ``` @@ -65,17 +70,17 @@ biig_domain: > Using PostPersistRule means that the flush of doctrine will (re)dispatch some events. If this is a great way to add features during your workflow... > This also means that using a Doctrine **flush** in a domain rule (even a different one) is something tricky. > -> However this package will not fail or end in infinite loop, it's 100% supported, but events order may be surprising. +> However, this package will not fail or end in infinite loop, it's 100% supported, but events order may be surprising. > > ⚠️⚠️⚠️⚠️⚠️⚠️⚠️ ### Symfony Integration -If you use the Symfony Bundle with auto-configuration of your services. +If you use the Symfony Bundle with autoconfiguration of your services. **You don't have anything to do.** -If you don't auto-discover your services and don't enable auto-configuration, then you will need to add the tag: +If you don't auto-discover your services and don't enable autoconfiguration, then you will need to add the tag: ```yaml My\Domain\Rule: tags: @@ -92,19 +97,14 @@ My\Domain\Rule: - { name: biig_domain.rule, event: 'your.event.name', method: 'execute', priority: 0 } ``` -_Notice: the priority field is optional._ +_Notice: the priority field is optional as well as method._ #### Configuration reference ```yaml biig_domain: - # It modifies the DoctrineBundle configuration to register a new - # ClassMetadataInfo class so the instantiator now set the domain event - # dispatcher to your models automatically - override_doctrine_instantiator: true - - # By default it will override the doctrine instantiator only for + # By default, it will override the doctrine instantiator only for # the "default" entity manager of your application. You can specify # many entity managers if you want. entity_managers: [] diff --git a/docs/injection_in_doctrine_entities.md b/docs/injection_in_doctrine_entities.md index db8ea6a..d863b3c 100644 --- a/docs/injection_in_doctrine_entities.md +++ b/docs/injection_in_doctrine_entities.md @@ -3,39 +3,31 @@ Injection of DomainEventDispatcher in Doctrine entities _This feature allows you to merge your doctrine entities with DDD model._ -_To achieve this goal it provides you a set of classes to extends doctrine behavior on entities instantiation._ +_To achieve this goal it provides you a set of classes to extends doctrine behavior on entity instantiation._ How it works ------------ Doctrine uses an `Instantiator` class to instantiate entities. (this is some kind of factory) -As this `Instantiator` is hardly instantiated by Doctrine, we need to extends the ORM core. Which mean -this feature **may** be in **conflict** with some other packages that may extends doctrine behavior (I don't know any). +As this `Instantiator` is hardly instantiated by Doctrine, we need to extend the ORM core. Which mean +this feature **may** be in **conflict** with some other packages that may extend doctrine behavior (I don't know any). ### Usage without integration ```php setClassMetadataFactoryName(new ClassMetadataFactory($dispatcher)); $entityManager = new \Doctrine\ORM\EntityManager($connection, $configuration); +$entityManager->getEventManager()->addEventSubscriber(new PostLoadDispatcherInjectionListener($dispatcher)); ``` ### Symfony integration -And then you can enable or disable this feature. Here is the default configuration: - -```yaml -biig_domain: - override_doctrine_instantiator: true -``` - ⚠ You need to know it ----------------------