Automatically dispatch updates to clients using the Mercure protocol #2282

dunglas · 2018-10-26T16:56:51Z

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

This PR adds support for the Mercure Protocol to API Platform.
It introduces a simple new attribute called mercure:

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(mercure=true)
 */
class Book
{
    // ...
}

When set, every time an object of this type is created, updates or deleted through the API, the new version is sent to all connected clients through the Mercure hub

Checkout this YouTube video to see how it works with the API Platform client generator: http://www.youtube.com/watch?v=JdlAcfTJsOI

The code of I used for this video is available here: api-platform/demo#66

It's also possible to send the update to users having some targets only:

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(mercure={"a-group", "another-group"})
 */
class Book
{
    // ...
}

Finally, it's possible to execute an expression (using the Expression Language component), to retrieve a dynamic list of targets:

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(mercure="object.owners")
 */
class Book
{
    public $owners = [];
   // ...
}

To enable Mercure support, you must install the brand new Symfony Mercure Bundle, that comes with the Symfony Mercure Component.

Take a look to my Forum PHP's slide deck for further information about Mercure and its support in Symfony and API Platform.

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

bendavies · 2018-10-29T12:43:40Z

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

+
+    public function __construct(ResourceClassResolverInterface $resourceClassResolver, IriConverterInterface $iriConverter, ResourceMetadataFactoryInterface $resourceMetadataFactory, SerializerInterface $serializer, MessageBusInterface $messageBus = null, callable $publisher = null, ExpressionLanguage $expressionLanguage = null)
+    {
+        if (null === $messageBus && null === $publisher) {


possibly ensure only 1 is provided?

It would make the wiring a bit harder.

bendavies · 2018-10-29T12:45:03Z

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

+
+    private function reset(): void
+    {
+        $this->createdEntities = new \SplObjectStorage();


is this the same as removeAll?

removeAll takes a mandatory argument as parameter.

indeed, $this->createdEntities->removeAll($this->createdEntities).

I was wondering if there would be any different from a memory/gc point of view.

No idea :) I would keep it as is for now because it's "safer", but if your suggestion improve GC or something similar, let me know and I'll update!

bendavies · 2018-10-29T12:48:05Z

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

+
+        if (\is_string($value)) {
+            if (null === $this->expressionLanguage) {
+                throw new RuntimeException('The Expression Language component is not installed. Try running "composer require symfony/expression-language".');


is this the proper place to throw this, or can it be done in the metadata factory somehow?

bendavies · 2018-10-29T12:48:24Z

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

+        }
+
+        if (!\is_array($value)) {
+            throw new InvalidArgumentException(sprintf('The value of the "mercure" attribute of the "%s" resource class must be a boolean, an array of targets or a valid expression, "%s" given.', $resourceClass, \gettype($value)));


as above, proper place for this?

We currently don't handle metadata validation in the factory, but it would definitely be a better place

would be nice huh!?

Yes. I'll keep it as is because it out of this PR's scope, and I'll try to add a proper validator (for all existing attributes) in a subsequent PR. Is it ok for you?

of course! sorry, my ?! wasn't meant to come off as rude or aggressive, but enthusiastic!

I understood it like that no worries :)

bendavies · 2018-11-05T14:38:35Z

src/Bridge/Symfony/Bundle/Resources/config/doctrine_orm_http_cache_purger.xml

@@ -15,7 +15,7 @@

            <tag name="doctrine.event_listener" event="preUpdate" />
            <tag name="doctrine.event_listener" event="onFlush" />
-            <tag name="doctrine.event_listener" event="postFlush" />
+            <tag name="kernel.event_listener" event="kernel.terminate" method="postFlush" />


oh, wow ok. has your thinking changed since #1286?

Hum, you're right, I'll revert this change as it's not related to this PR. (I forgot about this discussion)

but the discussion point is similar, i guess.

Not really, to me it's a big deal if a cache is not flushed because you'll serve stale data. Not dispatching a Mercure update is less a problem, because it breaks nothing, and it's explicitly stated in the Mercure protocol that the client MUST call the original API if it wants to be sure to have fresh data. So we can use kernel.terminate safely for Mercure, I'm still unsure for Varnish.

nicely argued.

soyuka · 2018-11-07T12:49:22Z

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php

@@ -145,7 +145,10 @@ private function storeEntityToPublish($entity, string $property): void
        }

        if ('deletedEntities' === $property) {
-            $this->deletedEntities[$this->iriConverter->getIriFromItem($entity, UrlGeneratorInterface::ABS_URL)] = $value;
+            $this->deletedEntities[(object) [


can we transform this to a real class? We had issues in the past with StdClass and it's better for debugging.

Does it worth it? It's a purely internal state.

https://github.com/api-platform/core/pull/1780/files this was kinda the same, internal state but eventually it hit a bug :p. As you want.

ooo. mine! that was for anonymous classes, not stdClass?

It was in the serialization context, and indeed an anonymous class. \stdClass is serializable: https://3v4l.org/2VWST

…pi-platform#2282) * Automatically dispatch updates to clients using the Mercure protocol * Allow to use different URL to publish and subscribe * Fix PHPStan * Use public repos * Remove useless arg * Review * Revert unrelated change * Don't deal with absolute IRIs in documents for now

dunglas mentioned this pull request Oct 26, 2018

Mercure demo api-platform/demo#66

Merged

dunglas changed the title ~~Mercure~~ Automatically dispatch updates to clients using the Mercure protocol Oct 26, 2018

antograssiot reviewed Oct 27, 2018

View reviewed changes

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php Show resolved Hide resolved

antograssiot mentioned this pull request Oct 27, 2018

Add tests on doctrine collection purge #2284

Merged

bendavies reviewed Oct 29, 2018

View reviewed changes

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php Outdated Show resolved Hide resolved

bendavies reviewed Oct 29, 2018

View reviewed changes

src/Bridge/Doctrine/EventListener/PublishMercureUpdatesListener.php Show resolved Hide resolved

bendavies reviewed Oct 29, 2018

View reviewed changes

dunglas added 4 commits November 5, 2018 14:55

Automatically dispatch updates to clients using the Mercure protocol

336e472

Allow to use different URL to publish and subscribe

a5a3948

Fix PHPStan

656ff13

Use public repos

d5fd181

dunglas force-pushed the mercure branch from fc43744 to 24b3507 Compare November 5, 2018 14:02

Remove useless arg

b80f8d6

dunglas force-pushed the mercure branch from 24b3507 to b80f8d6 Compare November 5, 2018 14:02

Review

a795a62

bendavies reviewed Nov 5, 2018

View reviewed changes

dunglas added 2 commits November 5, 2018 16:39

Revert unrelated change

023114d

Don't deal with absolute IRIs in documents for now

2f4c171

soyuka reviewed Nov 7, 2018

View reviewed changes

dunglas merged commit 516c9c7 into api-platform:master Nov 8, 2018

dunglas deleted the mercure branch November 8, 2018 11:39

This was referenced Nov 8, 2018

Add Mercure support in React and React Native generators + various improvements api-platform/create-client#94

Merged

Client Generator: Mercure support and various improvements api-platform/docs#648

Merged

dunglas mentioned this pull request Nov 14, 2018

Best way to return result after a long job api-platform/api-platform#862

Closed

dunglas mentioned this pull request Dec 22, 2018

Websocket support #2048

Closed

dunglas mentioned this pull request Jan 10, 2019

Docs for the Mercure support api-platform/docs#710

Merged

bendavies mentioned this pull request Mar 13, 2019

Publish mercure updates on flush #2578

Merged

Uh oh!

Automatically dispatch updates to clients using the Mercure protocol #2282

Automatically dispatch updates to clients using the Mercure protocol #2282

Uh oh!

Conversation

dunglas commented Oct 26, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bendavies Oct 29, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas Nov 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dunglas commented Oct 26, 2018 •

edited

Loading

bendavies Oct 29, 2018 •

edited

Loading

dunglas Nov 7, 2018 •

edited

Loading