Merge branch '5.2' into 5.3

* 5.2:
  Fix: Build
  [Mercure] integration with Symfony cli and various improvements

Author: OskarStark

.doctor-rst.yaml

@@ -105,3 +105,4 @@ whitelist:
         - '// bin/console'
         - 'End to End Tests (E2E)'
         - '.. code-block:: php'
+        - '.. _`a feature to test applications using Mercure`: https://github.com/symfony/panther#creating-isolated-browsers-to-test-apps-using-mercure-or-websocket'

mercure.rst

@@ -22,8 +22,9 @@ server to clients. It is a modern and efficient alternative to timer-based
 polling and to WebSocket.
 
 Because it is built on top `Server-Sent Events (SSE)`_, Mercure is supported
-out of the box in most modern browsers (Edge and IE require `a polyfill`_) and
-has `high-level implementations`_ in many programming languages.
+out of the box in most modern browsers (old versions of Edge and IE require
+`a polyfill`_) and has `high-level implementations`_ in many programming
+languages.
 
 Mercure comes with an authorization mechanism,
 automatic re-connection in case of network issues
@@ -65,34 +66,19 @@ clients.
 
 .. image:: /_images/mercure/schema.png
 
-An official and open source (AGPL) implementation of a Hub can be downloaded
-as a static binary from `Mercure.rocks`_.
+If you use the `Symfony Local Web Server </setup/symfony_server>`_ or `Symfony Docker`_,
+a Mercure Hub is automatically available.
 
-If you use `Symfony Docker`_,
-a Mercure Hub is already included and you can skip straight to the next section.
-
-On Linux and Mac, run the following command to start it:
-
-.. rst-class:: command-linux
-
-    $ SERVER_NAME=:3000 MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!' MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!' ./mercure run -config Caddyfile.dev
-
-On Windows run:
-
-.. rst-class: command-windows
-
-    > $env:SERVER_NAME=':3000'; $env:MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!'; $env:MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!'; .\mercure.exe run -config Caddyfile.dev
-
-.. note::
-
-    Alternatively to the binary, a Docker image, a Helm chart for Kubernetes
-    and a managed, High Availability Hub are also provided by Mercure.rocks.
+For production usage, an official and open source (AGPL) Hub based on the Caddy web server
+can be downloaded as a static binary from `Mercure.rocks`_.
+Alternatively to the binary, a Docker image, a Helm chart for Kubernetes
+and a managed, High Availability Hub are also provided.
 
 .. tip::
 
     The `API Platform distribution`_ comes with a Docker Compose configuration
     as well as a Helm chart for Kubernetes that are 100% compatible with Symfony,
-    and contain a Mercure hub.
+    and contain a build of the Caddy web server including a Mercure hub.
     You can copy them in your project, even if you don't use API Platform.
 
 Configuration
@@ -101,18 +87,30 @@ Configuration
 The preferred way to configure the MercureBundle is using
 :doc:`environment variables </configuration>`.
 
-Set the URL of your hub as the value of the ``MERCURE_PUBLISH_URL`` env var.
-The ``.env`` file of your project has been updated by the Flex recipe to
-provide example values.
-Set it to the URL of the Mercure Hub (``http://localhost:3000/.well-known/mercure`` by default).
+When MercureBundle has been installed, the ``.env`` file of your project
+has been updated by the Flex recipe to include the available env vars.
+
+If you use the Symfony Local Web Server or Symfony Docker,
+the default values are compatible with the provided Hub
+and you can skip straight to the next section.
 
-In addition, the Symfony application must bear a `JSON Web Token`_ (JWT)
-to the Mercure Hub to be authorized to publish updates.
+Otherwise, set the URL of your hub as the value of the ``MERCURE_URL``
+and ``MERCURE_PUBLIC_URL`` env vars.
+Sometimes a different URL must be called by the Symfony app (usually to publish),
+and the JavaScript client (usually to subscrribe). It's especially common when
+the Symfony app must use a local URL and the client-side JavaScript code a public one.
+In this case, ``MERCURE_URL`` must contain the local URL that will be used by the
+Symfony app (e.g. ``https://mercure/.well-known/mercure``), and ``MERCURE_PUBLIC_URL``
+the publicly available URL (e.g. ``https://example.com/.well-known/mercure``).
 
-This JWT should be stored in the ``MERCURE_JWT_TOKEN`` environment variable.
+The clients must also bear a `JSON Web Token`_ (JWT)
+to the Mercure Hub to be authorized to publish updates and, sometimes, to subscribe.
+
+This JWT should be stored in the ``MERCURE_JWT_SECRET`` environment variable.
 
 The JWT must be signed with the same secret key as the one used by
-the Hub to verify the JWT (``!ChangeMe!`` in our example).
+the Hub to verify the JWT (``!ChangeMe!`` in you use the Local Web Server or
+Symfony Docker).
 Its payload must contain at least the following structure to be allowed to
 publish:
 
@@ -136,7 +134,7 @@ public updates (see the authorization_ section for further information).
 
 .. caution::
 
-    Don't put the secret key in ``MERCURE_JWT_TOKEN``, it will not work!
+    Don't put the secret key in ``MERCURE_JWT_SECRET``, it will not work!
     This environment variable must contain a JWT, signed with the secret key.
 
     Also, be sure to keep both the secret key and the JWTs... secrets!
@@ -158,13 +156,14 @@ service, including controllers::
     // src/Controller/PublishController.php
     namespace App\Controller;
 
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Mercure\HubInterface;
     use Symfony\Component\Mercure\Update;
 
-    class PublishController
+    class PublishController extends AbstractController
     {
-        public function __invoke(HubInterface $hub): Response
+        public function publish(HubInterface $hub): Response
         {
             $update = new Update(
                 'http://example.com/books/1',
@@ -198,7 +197,7 @@ Subscribing to updates in JavaScript is straightforward:
 
 .. code-block:: javascript
 
-    const eventSource = new EventSource('http://localhost:3000/.well-known/mercure?topic=' + encodeURIComponent('http://example.com/books/1'));
+    const eventSource = new EventSource('/.well-known/mercure?topic=' + encodeURIComponent('http://example.com/books/1'));
     eventSource.onmessage = event => {
         // Will be called every time an update is published by the server
         console.log(JSON.parse(event.data));
@@ -211,7 +210,7 @@ as patterns:
 .. code-block:: javascript
 
     // URL is a built-in JavaScript class to manipulate URLs
-    const url = new URL('http://localhost:3000/.well-known/mercure');
+    const url = new URL('/.well-known/mercure', window.origin);
     url.searchParams.append('topic', 'http://example.com/books/1');
     // Subscribe to updates of several Book resources
     url.searchParams.append('topic', 'http://example.com/books/2');
@@ -241,43 +240,6 @@ as patterns:
 
     Test if a URI Template match a URL using `the online debugger`_
 
-Async dispatching
------------------
-
-Instead of calling the ``Publisher`` service directly, you can also let Symfony
-dispatching the updates asynchronously thanks to the provided integration with
-the Messenger component.
-
-First, be sure :doc:`to install the Messenger component </messenger>`
-and to configure properly a transport (if you don't, the handler will
-be called synchronously).
-
-Then, dispatch the Mercure ``Update`` to the Messenger's Message Bus,
-it will be handled automatically::
-
-    // src/Controller/PublishController.php
-    namespace App\Controller;
-
-    use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\Mercure\Update;
-    use Symfony\Component\Messenger\MessageBusInterface;
-
-    class PublishController
-    {
-        public function __invoke(MessageBusInterface $bus): Response
-        {
-            $update = new Update(
-                'http://example.com/books/1',
-                json_encode(['status' => 'OutOfStock'])
-            );
-
-            // Sync, or async (RabbitMQ, Kafka...)
-            $bus->dispatch($update);
-
-            return new Response('published!');
-        }
-    }
-
 Discovery
 ---------
 
@@ -324,7 +286,7 @@ and to subscribe to it:
             const hubUrl = response.headers.get('Link').match(/<([^>]+)>;\s+rel=(?:mercure|"[^"]*mercure[^"]*")/)[1];
 
             // Append the topic(s) to subscribe as query parameter
-            const hub = new URL(hubUrl);
+            const hub = new URL(hubUrl, window.origin);
             hub.searchParams.append('topic', 'http://example.com/books/{id}');
 
             // Subscribe to updates
@@ -348,7 +310,7 @@ of the ``Update`` constructor to ``true``::
 
     class PublishController extends AbstractController
     {
-        public function __invoke(HubInterface $hub): Response
+        public function publish(HubInterface $hub): Response
         {
             $update = new Update(
                 'http://example.com/books/1',
@@ -457,7 +419,7 @@ And here is the controller::
 
     class DiscoverController extends AbstractController
     {
-        public function __invoke(Request $request, Discovery $discovery, Authorization $authorization): Response
+        public function publish(Request $request, Discovery $discovery, Authorization $authorization): Response
         {
             $discovery->addLink($request);
 
@@ -602,7 +564,7 @@ During unit testing there is not need to send updates to Mercure.
 
 You can instead make use of the `MockHub`::
 
-    // tests/Functional/.php
+    // tests/FunctionalTest.php
     namespace App\Tests\Unit\Controller;
 
     use App\Controller\MessageController;
@@ -654,6 +616,10 @@ sent. Here is the HubStub implementation:
     App\Tests\Functional\Fixtures\HubStub:
         decorates: mercure.hub.default
 
+.. tip::
+
+    Symfony Panther has `a feature to test applications using Mercure`_.
+
 Debugging
 ---------
 
@@ -694,6 +660,51 @@ Enable the panel in your configuration, as follows:
 
 .. image:: /_images/mercure/panel.png
 
+Async dispatching
+-----------------
+
+.. tip::
+
+    Async dispatching is discouraged. Most Mercure hubs already
+    handle publications asynchronously and using Messenger is
+    usually not necessary.
+
+Instead of calling the ``Publisher`` service directly, you can also let Symfony
+dispatching the updates asynchronously thanks to the provided integration with
+the Messenger component.
+
+First, be sure :doc:`to install the Messenger component </messenger>`
+and to configure properly a transport (if you don't, the handler will
+be called synchronously).
+
+Then, dispatch the Mercure ``Update`` to the Messenger's Message Bus,
+it will be handled automatically::
+
+    // src/Controller/PublishController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Mercure\Update;
+    use Symfony\Component\Messenger\MessageBusInterface;
+
+    class PublishController extends AbstractController
+    {
+        public function publish(MessageBusInterface $bus): Response
+        {
+            $update = new Update(
+                'http://example.com/books/1',
+                json_encode(['status' => 'OutOfStock'])
+            );
+
+            // Sync, or async (Doctrine, RabbitMQ, Kafka...)
+            $bus->dispatch($update);
+
+            return new Response('published!');
+        }
+    }
+
+
 .. _`the Mercure protocol`: https://mercure.rocks/spec
 .. _`Server-Sent Events (SSE)`: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
 .. _`a polyfill`: https://github.com/Yaffle/EventSource
@@ -708,3 +719,4 @@ Enable the panel in your configuration, as follows:
 .. _`practical UI`: https://twitter.com/ChromeDevTools/status/562324683194785792
 .. _`the dedicated API Platform documentation`: https://api-platform.com/docs/core/mercure/
 .. _`the online debugger`: https://uri-template-tester.mercure.rocks
+.. _`a feature to test applications using Mercure`: https://github.com/symfony/panther#creating-isolated-browsers-to-test-apps-using-mercure-or-websocket