Symfony UX Notify
Edit this pageSymfony UX Notify
Symfony UX Notify is a Symfony bundle integrating server-sent native notifications in Symfony applications using Mercure. It is part of the Symfony UX initiative.
Installation
Before you start, make sure you have Symfony UX configured in your app.
Then, install this bundle using Composer and Symfony Flex:
1 2 3 4 5 6 7 8 9
$ composer require symfony/ux-notify
# Don't forget to install the JavaScript dependencies as well and compile
$ npm install --force
$ npm run watch
# or use yarn
$ yarn install --force
$ yarn watchAlso make sure you have at least version 3.0 of
@symfony/stimulus-bridge in your package.json file.
Usage
To use Symfony UX Notify you must have a running Mercure server and a properly configured notifier transport:
1 2 3 4 5 6
// config/packages/notifier.yaml
framework:
notifier:
chatter_transports:
myMercureChatter: '%env(MERCURE_DSN)%'Note
It is possible to specify the topics to send the notification in the MERCURE_DSN
environment variable by specifying the topics query parameter.
Otherwise, notifications will be sent to https://symfony.com/notifier topic.
Then, you can inject the NotifierInterface service and send messages on the chat/myMercureChatter channel:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
// ...
use Symfony\Component\Notifier\Notification\Notification;
use Symfony\Component\Notifier\NotifierInterface;
#[AsCommand(name: 'app:flash-sales:announce')]
class AnnounceFlashSalesCommand extends Command
{
public function __construct(private NotifierInterface $notifier)
{
parent::__construct();
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$this->notifier->send(new Notification('Flash sales has been started!', ['chat/myMercureChatter']));
return 0;
}
}Finally, to "listen" and trigger the notifications in the user's browser,
call the stream_notifications() Twig function anywhere on the page:
1 2
{{ stream_notifications() }}
{{ stream_notifications(['/my/topic/1', '/my/topic/2']) }}Note
Calling stream_notifications() without parameter will fallback to the
following unique topic: https://symfony.com/notifier.
Enjoy your server-sent native notifications!
Extend the Stimulus Controller
Symfony UX Notify allows you to extend its default behavior using a custom Stimulus controller:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
// assets/controllers/mynotify_controller.js
import { Controller } from '@hotwired/stimulus';
export default class extends Controller {
initialize() {
// guarantees "this" refers to this object in _onConnect
this._onConnect = this._onConnect.bind(this);
}
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:
1
{{ stream_notifications(options = {'data-controller': 'mynotify'}) }}Using another Mercure hub
Symfony UX Notify can be configured to specify the Mercure hub to use:
1 2 3 4 5
# config/packages/notify.yaml
notify:
# Specifies the Mercure hub to use. Defaults to "mercure.hub.default"
mercure_hub: mercure.hub.customBackward 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
