[Notify] Add Notify library

Author: mtarld

.github/workflows/test.yaml

@@ -101,6 +101,15 @@ jobs:
               run: php vendor/bin/simple-phpunit
               working-directory: src/LazyImage
 
+            - name: Notify Dependencies
+              uses: ramsey/composer-install@v2
+              with:
+                  working-directory: src/Notify
+                  dependency-versions: lowest
+            - name: Notify Tests
+              run: php vendor/bin/simple-phpunit
+              working-directory: src/Notify
+
     tests-php8-low-deps:
         runs-on: ubuntu-latest
         steps:
@@ -184,6 +193,14 @@ jobs:
               working-directory: src/LiveComponent
               run: php vendor/bin/simple-phpunit
 
+            - name: Notify Dependencies
+              uses: ramsey/composer-install@v2
+              with:
+                  working-directory: src/Notify
+            - name: Notify Tests
+              working-directory: src/Notify
+              run: php vendor/bin/simple-phpunit
+
     tests-js:
         runs-on: ubuntu-latest
         steps:

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/Configuration.php

@@ -0,0 +1,39 @@
+<?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\Config\Definition\Builder\TreeBuilder;
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+/**
+ * @author Mathias Arlaud <[email protected]>
+ *
+ * @internal
+ */
+final class Configuration implements ConfigurationInterface
+{
+    public function getConfigTreeBuilder(): TreeBuilder
+    {
+        $treeBuilder = new TreeBuilder('notify');
+        $rootNode = $treeBuilder->getRootNode();
+        $rootNode
+            ->children()
+                ->scalarNode('mercure_hub')
+                    ->info('Mercube hub service id')
+                    ->defaultValue('mercure.hub.default')
+                ->end()
+            ->end()
+        ;
+
+        return $treeBuilder;
+    }
+}

src/Notify/DependencyInjection/NotifyExtension.php

@@ -0,0 +1,43 @@
+<?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\Reference;
+use Symfony\Component\HttpKernel\DependencyInjection\ConfigurableExtension;
+use Symfony\UX\Notify\Twig\NotifyExtension as TwigNotifyExtension;
+use Symfony\WebpackEncoreBundle\Twig\StimulusTwigExtension;
+use Twig\Environment;
+
+/**
+ * @author Mathias Arlaud <[email protected]>
+ *
+ * @internal
+ */
+final class NotifyExtension extends ConfigurableExtension
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function loadInternal(array $config, ContainerBuilder $container)
+    {
+        if (class_exists(Environment::class) && class_exists(StimulusTwigExtension::class)) {
+            $container->register('notify.twig_extension', TwigNotifyExtension::class)
+                ->setArguments([
+                    new Reference($config['mercure_hub']),
+                    new Reference('webpack_encore.twig_stimulus_extension'),
+                ])
+                ->addTag('twig.extension')
+            ;
+        }
+    }
+}

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,133 @@
+# 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.
+
+## Configuration
+
+```yaml
+# config/packages/notify.yaml
+
+notify:
+    # Specifies the Mercure hub to use. Defaults to "mercure.hub.default"
+    mercure_hub: mercure.hub.custom
+```
+
+## 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' #}
+```
+
+### 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
+```