[Proposal] Internal events #2506

alanpoulain · 2019-02-10T19:48:52Z

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	?
Deprecations?	no
Tests pass?	yes
Fixed tickets
License	MIT
Doc PR

Alternative to #2329.

The aim is the same as the other PR but also to decouple the event system from Symfony as much as possible (to replace it easily with Laravel for instance).

The listeners in ApiPlatform\Core\EventListener listen to our internal events instead of the Symfony ones.

The Symfony events are listened by the EventDispatcher in the Bridge and dispatched as our events. It implies that the symfony/event-dispatcher dependency is now mandatory.

It will also simplify the part about priorities (https://api-platform.com/docs/core/events/#the-event-system) since the user has now to only listen to our events.

For existing applications, it should not change anything since listening to Symfony events (with priority) is equivalent to listening to our internal ones. For the listeners should we add deprecations about using Symfony events?

WDYT? @api-platform/core-team?

alanpoulain · 2019-02-10T19:53:09Z

src/Events.php

+final class Events
+{
+    public const PRE_READ = 'api_platform.pre_read';
+    public const READ = 'api_platform.read';


This event will not be used by GraphQL and is internal. Should we expose it elsewhere? Should we call it something else (api_platform.rest.read)?

WDYT about keeping this event name, and dispatch a api_platform.query event for GraphQL?

I don't understand how the api_platform.read event could be only internal and not listened by any listener in a project

For GraphQL, there will be no event like this dispatched (only pre and post). GraphQL is working differently. Using query does not work: there is a read step in the mutation resolver for example.
api_platform.read could be listened, but it shouldn't since it is used by our ReadListener.

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

vincentchalamon · 2019-02-10T20:12:17Z

src/EventListener/ReadListener.php

@@ -52,9 +51,9 @@ public function __construct(CollectionDataProviderInterface $collectionDataProvi
     *
     * @throws NotFoundHttpException
     */
-    public function onKernelRequest(GetResponseEvent $event)
+    public function handleEvent(EventInterface $event)


This is a BC break, as you change a public method definition (for example, if any project overrides this service using service decoration)

Yes sure. Maybe I will add a deprecation. It's too related to Symfony right now IMO.

vincentchalamon · 2019-02-10T20:22:42Z

I like the idea of this bridge of the EventDispatcher, it makes API Platform more flexible and compatible with other systems (such as Laravel as you said).

For the listeners should we add deprecations?

Do you mean adding deprecations about listening to Symfony events in an API Platform project?

Taluu · 2019-02-10T21:52:45Z

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

+
+        switch ($event) {
+            case $event instanceof GetResponseEvent:
+                $internalEvent = new $this->eventClass(null, ['request' => $event->getRequest()]);


How about putting the original event in the internal event ?

Not sure about this. I want to decouple from Symfony as much as possible. What is the use case?

The GetResponseEvent from Symfony has a response part which is not in the internal event, it could be useful to have it here.

Yes but it's only to set the response and bypass everything else. I'm not sure we want this in API Platform, do we? If there are a "response" (controller result) and a request (in GetResponseForControllerResultEvent for instance), I will add them both to the context.

Yup, but then what if we get an exception event (GetResponseForExceptionEvent I think ?), and we want to get the thrown exception ? Same for all the other sub events.

I will add an exception field in the context then. IMO we want as much information as the Symfony event but we don't want to use the event itself since it's too tight to Symfony.

Then the case should be split accordingly depending on the event it handles (exception, controller result, ... and so on)

alanpoulain · 2019-02-10T21:58:48Z

@vincentchalamon yes I mean that for the deprecations.

ragboyjr · 2019-02-10T22:50:15Z

@alanpoulain this is huge 👍 from me. One of the main things that confused me when first looking over API platform was that it felt a bit hackish if we wanted to extend specific API platform events because it was based on ensuring priority after api platform event listeners on SF events.

This seems like it will not only make API Platform easier to fit on other popular frameworks, but will also make extending API platform specific events easier for users.

Taluu · 2019-02-11T09:01:41Z

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

+                $internalEvent = new $this->eventClass(null, ['request' => $event->getRequest()]);
+        }
+
+        $this->dispatcher->dispatch($this->eventName, $internalEvent);


if the internal event is null, how about dispatching the given event instead ?

Why would it be null? I'm thinking of throwing an exception instead (it would mean the service is not configured correctly).

As this service is kinda decorating the event dispatcher, if you want to dispatch other events, you will dispatch a null event instead. I think this can be a huge source of bugs or miscomprehension.

Unless this service is really for internal...

Yes I think it's really internal. If a user want to do something like this, it can do it itself. Maybe adding a @internal for the class would be a good idea.

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

Taluu · 2019-02-11T10:02:19Z

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

+
+        switch ($event) {
+            case $event instanceof GetResponseEvent:
+                $internalEvent = new $this->eventClass(null, ['request' => $event->getRequest()]);


Then the case should be split accordingly depending on the event it handles (exception, controller result, ... and so on)

Taluu · 2019-02-11T10:03:44Z

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

+    private $eventClass;
+    private $dispatcher;
+
+    public function __construct(string $eventName, string $eventClass, EventDispatcherInterface $dispatcher)


so this dispatcher can handle only one event ? you would have for X events (read, write, ... and so on) X declared services ? Wouldn't that be a mess ? :O

Taluu · 2019-02-11T10:04:07Z

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php

+    public function __construct(string $eventName, string $eventClass, EventDispatcherInterface $dispatcher)
+    {
+        $this->eventName = $eventName;
+        $this->eventClass = $eventClass;


not having any check if the event class given is valid is a foot gun IMO

dunglas · 2019-02-12T06:46:43Z

I'm wondering if we the latest addition in the library, we still need an event system. If we look at the diagram created with @soyuka (we'll provide an updated version soon), we already have extension point everywhere we need.

Maybe could we just remove the event system from the docs (it will become purely internal), and document how to hook custom logic during the execution flow:

custom data provider
custom deserializer
custom validator
custom data persister
custom serializer

It's simple, covers all use cases, and is compatible with Laravel, PSR-7 middleware and so on. WDYT?

alanpoulain · 2019-02-12T11:28:00Z

@dunglas Why not. But we will need to keep the event listeners anyway, don't we? And it's better if they are decoupled from Symfony.

And I'm not sure if creating a custom persister for instance is a good idea for having a side-effect (send a mail for example). Are you sure it's easier than creating an event listener?

Also I don't think it's only documentation. We need a ChainValidator for example don't we?

dunglas · 2019-02-12T15:00:06Z

But we will need to keep the event listeners anyway, don't we?

We'll always need to plug on the Symfony kernel, anyway.

Are you sure it's easier than creating an event listener?

I'm not sure, it's just some thought to start the discussion :)

We need a ChainValidator for example don't we?

Not really, the user can create custom validation constraints by using the Symfony component, or implement the ValidatorInterface himself if he (or she) wants too.

alanpoulain · 2019-02-12T15:10:43Z

We'll always need to plug on the Symfony kernel, anyway.

Sure but it will be done in the bridge, and could be easily replaced with another listener. Not the case for the current event listeners because there are too tight to Symfony.

I think it's really easier to use events for side-effets than having to deal with custom services. I think both methods are complementary.

soyuka · 2019-02-15T13:31:34Z

And I'm not sure if creating a custom persister for instance is a good idea for having a side-effect (send a mail for example). Are you sure it's easier than creating an event listener?

To me this is a job for the messenger.

I think it's really easier to use events for side-effets than having to deal with custom services. I think both methods are complementary.

Yes but using too many events can become a mess pretty fast.

Updated schema with transformers:

IMO we should try to deprecate the use of events as much as possible. Of course we'd have to keep symfony events but I'm not in favor of adding internal events like this. If we look at the above schema, the end developper should be able to hook using our concepts (persister, provider, transformer) for most of the use cases.
If the use case is really specific, events may be a good solution but they should not be the developer first choice, which is what internal events tend to give.

alanpoulain · 2019-02-15T13:45:10Z

To me this is a job for the messenger.

All projects don't always use the Messenger component whereas events are pretty common.

Of course we'd have to keep symfony events but I'm not in favor of adding internal events like this.

If we keep the Symfony events, it's always better to decouple our event listeners from Symfony. This is also the aim of this PR.

If the use case is really specific, events may be a good solution but they should not be the developer first choice, which is what internal events tend to give.

Why? Listening to our internal events or listening to the Symfony events, I don't really see the difference. If a developer wants to do it, it will always find a way. We can outline in the documentation that this shouldn't be the first choice, but that's all.

jamesisaac · 2019-02-28T00:20:57Z

And I'm not sure if creating a custom persister for instance is a good idea for having a side-effect (send a mail for example). Are you sure it's easier than creating an event listener?

To me this is a job for the messenger.

This is over complicating things IMO. I think it's great that with API Platform it's so simple to get a REST and/or GraphQL API up and running by simply defining the entities and a bit of configuration via annotations. But unlike similar tools which also provide these capabilities (Prisma, PostGraphile, etc), you can also very easily hook in custom business logic (e.g. side effects like sending email) through Symfony's events system. Deploying to something like Heroku is then just a few clicks away.

If I understand the Messenger component correctly, you're now talking about orchestrating multiple projects/services, replacing function calls with inter-process message queues. Sure, there's a place for that (bigger projects with lots of devops resources), but for rapidly shipping MVPs, the single project "monolith" approach greatly simplifies things. IMO, API Platform is currently the best in class for this use-case, and GraphQL events is one of the only gaps in offering full flexibility (as I experienced in #2167).

teohhanhui · 2019-03-05T16:06:35Z

I'd suggest we stick to semantical events, in this case CRUD.

The goal should not be to replicate our existing event listeners / priorities, but to provide hooks where they are valuable and have well-defined semantics.

alanpoulain · 2019-03-05T16:36:03Z

@teohhanhui I don't fully grasp what you say. My aim is to have our own events (to be decoupled from Symfony). And with them, users can add hooks if they want.

teohhanhui · 2019-03-05T17:57:26Z

What I mean is, if we're going to have custom events, then those events should have well-defined semantics, not something like "add format" / "deserialize" which is merely an implementation detail. Having CRUD events would be good.

alanpoulain · 2019-03-05T20:00:34Z

I'm not sure what you mean by CRUD events. We need a way for the user to modify things before or after our listeners. And we need these events for ourselves too.

soyuka · 2019-03-06T08:38:51Z

He probably means that the user should be able to hook to:

PRE_CREATE
POST_CREATE
PRE_READ
POST_READ
PRE_UPDATE
POST_UPDATE
PRE_DELETE
POST_DELETE

This is independent from the implementation, and by the way I've reviewed my thoughts about having internal events and I think it might be good to detach these from symfony.

alanpoulain · 2019-03-06T09:01:15Z

Adding these events later should be really easy with this implementation (just more events to dispatch).
But they can't replace the already existing events.

dunglas · 2019-03-11T15:30:59Z

src/Event/EventInterface.php

+{
+    public function getData();
+
+    public function setData($data): void;


If we introduce our own event system, I would like to use immutability (as in our metadata system).

dunglas · 2019-03-11T15:32:28Z

src/EventListener/ReadListener.php

+    public function handleEvent(/*EventInterface */$event)
+    {
+        if ($event instanceof EventInterface) {
+            $request = $event->getContext()['request'];


This is a hard coupling to Symfony. We should let the user injecting RequestStack instead of populating this key.

dunglas · 2019-03-11T15:33:41Z

src/Events.php

+    public const FORMAT_ADD = 'api_platform.format_add';
+
+    public const PRE_READ = 'api_platform.pre_read';
+    public const READ = 'api_platform.read';


Couldn't we only have the PRE ad POST events?

I was thinking that PRE and POST events were for the user whereas the other ones were for our internal use only.

ragboyjr · 2019-03-11T20:23:46Z

@jamesisaac Regarding using messenger, it's just used as a command bus in here and doesn't necessarily need to be hooked up to an actual async sending system.

teohhanhui · 2019-04-02T13:22:59Z

We need a way for the user to modify things before or after our listeners. And we need these events for ourselves too.

These listeners are supposed to be the integration with the Symfony framework. We should extract out all logic from the listeners, instead of going the other way round. So I'm strongly -1 for having implementation-specific events.

It will really tie our hands in the future, as we will need to keep supporting events that make no sense anymore, as our implementation evolves. Leaking implementation details is always a bad thing, and this includes having events that are so closely tied to our current implementation. That's what I meant by "semantics". These events are meaningless beyond a specific implementation.

alanpoulain · 2019-04-02T13:30:17Z

Not sure about your position. For me, API Platform is based on events and will always relies on an event system. No need to extract the logic from the listeners, we only need them to be decorrelated from the Symfony framework.

It will tie our hands in the future.

I don't see why. Our hands are tied today because we are too coupled to Symfony.

teohhanhui · 2019-04-02T13:47:53Z

The way to decouple from Symfony framework, is to extract all logic out from listeners - "thin listeners". Same thing that we do for controllers - "thin controllers". Then we can integrate with different frameworks by reusing the services that we have. Listeners are just glue code.

alanpoulain · 2019-04-02T14:18:27Z

You can consider this PR as a first step to do this then? First we decouple, then we extract the logic?

teohhanhui · 2019-04-03T12:06:10Z

No, we decouple by extracting the logic, not by creating implementation-specific events. This is completely going in the wrong direction. I've explained in detail above. So I have nothing more to add.

alanpoulain · 2019-04-03T13:26:00Z

I'm not convinced then and I think this PR is worth finishing. And with it GraphQL will have an event system.

teohhanhui · 2019-04-03T13:41:22Z

I'm not against having our own events. In fact, it'll be wonderful. If the events have well-defined semantics and decoupled from implementation, then I have no objections.

I gave the example of CRUD events, as those are the most obvious (and probably already will provide enough flexibility anyway). But we could come up with other well-defined events. Taking our existing listeners implementation and creating events from those is the opposite of that.

alanpoulain · 2019-04-03T13:44:42Z

You're probably right but I don't want to refactor the planet with this PR. Couldn't it be done in another PR once this one is merged?

Co-authored-by: ArnoudThibaut <thibaut.arnoud@gmail.com>

Goutte · 2019-08-26T16:12:18Z

I'm not against having our own events. In fact, it'll be wonderful. If the events have well-defined semantics and decoupled from implementation, then I have no objections.

It would be wonderful to have CRUD events.

This thread was my lifeline for information after many google queries ; could someone be awesome and link to a current discussion about the subject, if any? @alanpoulain

jamesisaac · 2019-08-26T16:15:33Z

@Goutte #2978 seems to be the latest iteration on this subject

alanpoulain commented Feb 10, 2019

View reviewed changes

vincentchalamon reviewed Feb 10, 2019

View reviewed changes

src/Bridge/Symfony/Bundle/EventListener/EventDispatcher.php Outdated Show resolved Hide resolved

vincentchalamon reviewed Feb 10, 2019

View reviewed changes

Taluu approved these changes Feb 10, 2019

View reviewed changes

soyuka mentioned this pull request Feb 11, 2019

Improve Input/Output with normalizers #2495

Merged

Taluu reviewed Feb 11, 2019

View reviewed changes

alanpoulain force-pushed the internal-events branch from 2e69d85 to 3357370 Compare February 15, 2019 13:49

alanpoulain force-pushed the internal-events branch from 3357370 to 586872d Compare February 27, 2019 17:00

alanpoulain force-pushed the internal-events branch from 586872d to 4c54984 Compare March 2, 2019 17:59

alanpoulain added the [WIP] Work In Progress label Mar 2, 2019

alanpoulain force-pushed the internal-events branch from 4c54984 to b7dbb8f Compare March 2, 2019 18:14

dunglas requested changes Mar 11, 2019

View reviewed changes

Deuchnord mentioned this pull request Apr 1, 2019

WIP: Add events #2329

Closed

5 tasks

alanpoulain force-pushed the internal-events branch 3 times, most recently from 890ce6d to 6c8b29f Compare April 7, 2019 08:47

soyuka mentioned this pull request Apr 7, 2019

Add a ResourceEventSubscriber #1629

Closed

antograssiot added the ⭐ EU-FOSSA Hackathon label Apr 7, 2019

alanpoulain force-pushed the internal-events branch 5 times, most recently from fc607d8 to cdc9608 Compare April 7, 2019 14:55

Internal events

a0ecc42

Co-authored-by: ArnoudThibaut <thibaut.arnoud@gmail.com>

alanpoulain force-pushed the internal-events branch from cdc9608 to a0ecc42 Compare April 7, 2019 15:19

alanpoulain closed this Aug 10, 2019

[Proposal] Internal events #2506

[Proposal] Internal events #2506

Conversation

alanpoulain commented Feb 10, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincentchalamon Feb 10, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vincentchalamon commented Feb 10, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alanpoulain Feb 11, 2019 • edited Loading

Choose a reason for hiding this comment

Taluu Feb 11, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alanpoulain commented Feb 10, 2019

ragboyjr commented Feb 10, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alanpoulain Feb 11, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dunglas commented Feb 12, 2019 • edited Loading

alanpoulain commented Feb 12, 2019

dunglas commented Feb 12, 2019

alanpoulain commented Feb 12, 2019

soyuka commented Feb 15, 2019

alanpoulain commented Feb 15, 2019

jamesisaac commented Feb 28, 2019

teohhanhui commented Mar 5, 2019 • edited Loading

alanpoulain commented Mar 5, 2019

teohhanhui commented Mar 5, 2019

alanpoulain commented Mar 5, 2019

soyuka commented Mar 6, 2019

alanpoulain commented Mar 6, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ragboyjr commented Mar 11, 2019

teohhanhui commented Apr 2, 2019 • edited Loading

alanpoulain commented Apr 2, 2019

teohhanhui commented Apr 2, 2019 • edited Loading

alanpoulain commented Apr 2, 2019

teohhanhui commented Apr 3, 2019 • edited Loading

alanpoulain commented Apr 3, 2019

teohhanhui commented Apr 3, 2019

alanpoulain commented Apr 3, 2019

Goutte commented Aug 26, 2019

jamesisaac commented Aug 26, 2019

alanpoulain commented Feb 10, 2019 •

edited

Loading

vincentchalamon Feb 10, 2019 •

edited

Loading

alanpoulain Feb 11, 2019 •

edited

Loading

Taluu Feb 11, 2019 •

edited

Loading

alanpoulain Feb 11, 2019 •

edited

Loading

dunglas commented Feb 12, 2019 •

edited

Loading

teohhanhui commented Mar 5, 2019 •

edited

Loading

teohhanhui commented Apr 2, 2019 •

edited

Loading

teohhanhui commented Apr 2, 2019 •

edited

Loading

teohhanhui commented Apr 3, 2019 •

edited

Loading