Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Bundles
  4. Symfony UX Notify
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installation
  • Usage
    • Extend the Stimulus Controller
    • Using another Mercure hub
  • Backward Compatibility promise

Symfony UX Notify

Edit this page

Symfony 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 watch

Also 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!

Example of a native notification

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.custom

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

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:

    Symfony UX is backed by

    Put the code quality back at the heart of your project

    Put the code quality back at the heart of your project

    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Patrick Allaert, a Symfony contributor

    Thanks Patrick Allaert for being a Symfony contributor

    2 commits • 11 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony