[Notify] Add Notify library

Author: mtarld

.github/workflows/test.yaml

@@ -50,6 +50,11 @@ jobs:
                   cd src/LazyImage
                   composer update --prefer-lowest --prefer-dist --no-interaction --no-ansi --no-progress
                   php vendor/bin/simple-phpunit
+            - name: Notify
+              run: |
+                  cd src/Notify
+                  composer update --prefer-lowest --prefer-dist --no-interaction --no-ansi --no-progress
+                  php vendor/bin/simple-phpunit
 
     tests-php8-low-deps:
         runs-on: ubuntu-latest
@@ -108,6 +113,11 @@ jobs:
                   php ../../.github/build-packages.php
                   composer update --prefer-dist --no-interaction --no-ansi --no-progress
                   php vendor/bin/simple-phpunit
+            - name: Notify
+              run: |
+                  cd src/Notify
+                  composer update --prefer-dist --no-interaction --no-ansi --no-progress
+                  php vendor/bin/simple-phpunit
 
     tests-js:
         runs-on: ubuntu-latest

src/Notify/.gitattributes

@@ -0,0 +1,5 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/phpunit.xml.dist export-ignore
+/Resources/assets/test export-ignore
+/Tests export-ignore

src/Notify/.gitignore

@@ -0,0 +1,4 @@
+/vendor/
+.phpunit.result.cache
+.php_cs.cache
+composer.lock

src/Notify/DependencyInjection/NotifyExtension.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Notify\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Definition;
+use Symfony\Component\DependencyInjection\Reference;
+use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+use Symfony\UX\Notify\Twig\NotifyExtension as TwigNotifyExtension;
+use Twig\Environment;
+
+/**
+ * @author Mathias Arlaud <[email protected]>
+ *
+ * @internal
+ */
+class NotifyExtension extends Extension
+{
+    public function load(array $configs, ContainerBuilder $container)
+    {
+        if (class_exists(Environment::class)) {
+            $container
+                ->setDefinition('notify.twig_extension', new Definition(TwigNotifyExtension::class))
+                ->addArgument(new Reference('mercure.hub.default'))
+                ->addArgument(new Reference('webpack_encore.twig_stimulus_extension'))
+                ->addTag('twig.extension')
+                ->setPublic(false)
+            ;
+        }
+    }
+}

src/Notify/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2020-2021 Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

src/Notify/NotifyBundle.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Notify;
+
+use Symfony\Component\HttpKernel\Bundle\Bundle;
+
+/**
+ * @author Mathias Arlaud <[email protected]>
+ *
+ * @final
+ * @experimental
+ */
+class NotifyBundle extends Bundle
+{
+}

src/Notify/README.md

@@ -0,0 +1,166 @@
+# Symfony UX Notify
+
+Symfony UX Notify is a Symfony bundle integrating realtime native notifications in Symfony applications using [Mercure](https://mercure.rocks/).
+It is part of [the Symfony UX initiative](https://symfony.com/ux).
+
+## Installation
+
+Symfony UX Notify requires PHP 7.2+ and Symfony 5.3+.
+
+Install this bundle using Composer and Symfony Flex:
+
+```sh
+composer require symfony/ux-notify
+
+# Don't forget to install the JavaScript dependencies as well and compile
+yarn install --force
+yarn encore dev
+```
+
+Also make sure you have at least version 3.0 of [@symfony/stimulus-bridge](https://github.com/symfony/stimulus-bridge) in your `package.json` file.
+
+## Usage
+
+To use Symfony UX Notify you must have a [running Mercure server](https://symfony.com/doc/current/mercure.html#running-a-mercure-hub).
+
+Then, inject the `NotifierInterface` service and send messages on the `chat/mercure` channel.
+
+```php
+// ...
+use Symfony\Component\Notifier\Notification\Notification;
+use Symfony\Component\Notifier\NotifierInterface;
+
+class AnnounceFlashSalesCommand extends Command
+{
+    protected static $defaultName = 'app:flash-sales:announce';
+    private $notifier;
+
+    public function __construct(NotifierInterface $notifier)
+    {
+        parent::__construct();
+
+        $this->notifier = $notifier;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->notifier->send(new Notification('Flash sales has been started!', ['chat/mercure']));
+
+        return 0;
+    }
+}
+```
+
+Finally, native notifications could be displayed using the `notify` Twig function:
+
+```twig
+{{ stream_notifications(['/my/topic/1', '/my/topic/2']) }}
+{{ stream_notifications() }}
+
+{# Calling notify without parameter will fallback to the following unique topic: 'https://symfony.com/notifier' #}
+```
+
+### Using another Mercure hub
+By default, the `stream_notifications` is streaming the default Mercure hub. If you wanna change that behavior, you can use a compiler pass:
+
+``` php
+// src/DependencyInjection/UseCustomNotifyMercureHubCompilerPass.php
+
+namespace App\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+final class UseCustomNotifyMercureHubCompilerPass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container): void
+    {
+        $container->getDefinition('notify.twig_extension')
+            ->replaceArgument(0, new Reference('mercure.hub.custom'));
+    }
+}
+```
+
+``` php
+// src/Kernel.php
+
+namespace App;
+
+use App\DependencyInjection\UseCustomNotifyMercureHubCompilerPass;
+use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\HttpKernel\Kernel as BaseKernel;
+
+final class Kernel extends BaseKernel
+{
+    use MicroKernelTrait;
+
+    protected function build(ContainerBuilder $container): void
+    {
+        $container->addCompilerPass(new UseCustomNotifyMercureHubCompilerPass());
+    }
+}
+```
+
+### Extend the default behavior
+
+Symfony UX Notify allows you to extend its default behavior using a custom Stimulus controller:
+
+```js
+// mynotify_controller.js
+
+import { Controller } from '@hotwired/stimulus';
+
+export default class extends Controller {
+    connect() {
+        this.element.addEventListener('notify:connect', this._onConnect);
+    }
+
+    disconnect() {
+        // You should always remove listeners when the controller is disconnected to avoid side effects
+        this.element.removeEventListener('notify:connect', this._onConnect);
+    }
+
+    _onConnect(event) {
+        // Event sources have just been created
+        console.log(event.detail.eventSources);
+
+        event.detail.eventSources.forEach((eventSource) => {
+            eventSource.addEventListener('message', (event) => {
+                console.log(event); // You can add custom behavior on each event source
+            });
+        });
+    }
+}
+```
+
+Then in your render call, add your controller as an HTML attribute:
+
+```twig
+{{ stream_notifications(options = {'data-controller': 'mynotify'}) }}
+```
+
+## Backward Compatibility promise
+
+This bundle aims at following the same Backward Compatibility promise as the Symfony framework:
+[https://symfony.com/doc/current/contributing/code/bc.html](https://symfony.com/doc/current/contributing/code/bc.html)
+
+However it is currently considered
+[**experimental**](https://symfony.com/doc/current/contributing/code/experimental.html),
+meaning it is not bound to Symfony's BC policy for the moment.
+
+## Run tests
+
+### PHP tests
+
+```sh
+php vendor/bin/simple-phpunit
+```
+
+### JavaScript tests
+
+```sh
+cd Resources/assets
+yarn test
+```