Download the PHP package tobento/service-notifier without Composer

Notifier Service

Notifier interface for PHP applications using Symfony Notifier as default implementation.

Table of Contents

• Getting started
  • Requirements
  • Highlights
• Documentation
  • Basic Usage
    • Creating And Sending Notifications
  • Notifier
    • Create Notifier
    • Composite Notifier
  • Notifications
    • Notification
    • Abstract Notification
  • Recipients
    • Recipient
    • Address Recipient
    • User Recipient
    • Guest Recipient
    • Composite Recipient
  • Channel
    • Mail Channel
      • Mail Notification
      • Mail Recipient
      • Mail Channel Factory
    • Sms Channel
      • Sms Notification
      • Sms Recipient
    • Chat Channel
      • Chat Notification
      • Chat Recipient
      • Chat Channel Per Recipient
    • Push Channel
      • Push Notification
      • Push Recipient
    • Storage Channel
      • Storage Notification
      • Storage Recipient
      • Accessing Storage Notifications
    • Browser Channel
      • Browser Notification
      • Browser Recipient
      • Accessing Browser Notifications
  • Channels
    • Default Channels
    • Lazy Channels
  • Queue
  • Events
• Credits

  ---

Getting started

Add the latest version of the notifier service project running this command.

Requirements

• PHP 8.4 or greater

Highlights

• Framework-agnostic, will work with any project
• Decoupled design

Documentation

Basic Usage

Creating And Sending Notifications

Once you have created the notifier you can create and send notifications:

Check out the Notifications section to learn more about the available notifications you can create or you might create your own notification class fitting your application.

Check out the Recipients section to learn more about the available recipients you can create or you might create your own recipient class fitting your application.

Notifier

Create Notifier

Check out the Channels section to learn more about the available channels.

Composite Notifier

A notifier that forwards the notification to multiple notifiers at once.

Notifications

Notification

The may be used to create simple notification messages supporting all channels.

If you want to support custom channels you may consider creating a custom notification!

Available methods

In addition, you may add messages for specific channels:

Abstract Notification

Use the if you want to create specific messages for each channel.

Simply extend from the and add the message interfaces with its method you want to support.

Furthermore, any methods such as will receive a entity, the name and you may request any service being resolved (autowired) by the container.

Recipients

Recipient

The may be used to create a recipient supporting all channels.

Address Recipient

The may be used if you have installed the User Service.

User Recipient

The may be used if you have installed the User Service.

Guest Recipient

The represents a recipient that does not necessarily have a persistent user identity.

It is useful for scenarios such as:

• anonymous visitors
• temporary browser sessions
• browser-specific identifiers (cookie, session, token, etc.)
• broadcast-style notifications
• any custom identification strategy your application defines

Guest recipients behave like any other recipient but offer additional flexibility for browser-based or temporary notification delivery.

The id may be:

• null - meaning the notification is not tied to a specific user
• a string or integer - if your application assigns a temporary or custom identifier

The Notifier does not enforce a specific meaning for the ID.
You are free to choose how guests are identified in your application.

Composite Recipient

The may be used to compose the recipient from multiple recipients. The first found address will be used.

Channel

Mail Channel

The mail channel uses the Mail Service to send notifications.

Mail Notification

To send mail notifications you have multiple options:

Using the Abstract Notification

Simply extend from the and implement the interface. The interface requires a method which is already added on the defining the method as the message handler. You will just need to add the method which will receive a entity, the name and you may request any service being resolved (autowired) by the container.

If you do not have defined a default from address, you will need to set it on each message:

Using the Notification

Check out the Mail Message section to learn more about mail messages.

Mail Recipient

When sending notifications via the mail channel, the channel will call the method on the recipient entity to get the email address when no were defined on the mail message.

Mail Channel Factory

Sms Channel

Use the to create a SMS channel using the Symfony SMS Channel:

You will need to install any chat service you would like e.g.

Sms Notification

To send SMS notifications you have multiple options:

Using the Abstract Notification

Simply extend from the and implement the interface. The interface requires a method which is already added on the defining the method as the message handler. You will just need to add the method which will receive a entity, the name and you may request any service being resolved (autowired) by the container.

Using the Notification

Sms Recipient

When sending notifications via the sms channel, the channel will call the method on the recipient entity to get the sms address when no specific were defined.

Chat Channel

Use the to create a chat channel using the Symfony Chat Channel:

You will need to install any chat service you would like e.g.

Chat Notification

To send chat notifications you have multiple options:

Using the Abstract Notification

Simply extend from the and implement the interface. The interface requires a method which is already added on the defining the method as the message handler. You will just need to add the method which will receive a entity, the name and you may request any service being resolved (autowired) by the container.

Using the Notification

Chat Recipient

When sending notifications via the chat channel, you may add a specific channel address with parameters for later usage.

Sample notification with address usage

Chat Channel Per Recipient

When delivering notifications through the chat channel, you can assign a dedicated chat address to each recipient:

Channel Configuration

You can configure the to ensure that a message is only sent if the recipient has a chat address defined. If no address exists, you may specify an alternative chat channel to handle delivery:

Push Channel

Use the to create a push channel using the Symfony Push Channel:

You will need to install any push service you would like e.g.

Push Notification

To send push notifications you have multiple options:

Using the Abstract Notification

Simply extend from the and implement the interface. The interface requires a method which is already added on the defining the method as the message handler. You will just need to add the method which will receive a entity, the name and you may request any service being resolved (autowired) by the container.

Using the Notification

Push Recipient

When sending notifications via the push channel, you may add a specific channel address with parameters for later usage.

Sample notification with address usage

Storage Channel

The storage channel stores the notification information in the configured storage repository.

Check out the Repository Service to learn more about it.

The storage needs to have the following table columns:

Storage Repository

You may use the provided StorageRepository::class as the repository implementation for storing notifications.

To use it, install the storage repository service:

Check out the Storage Service - Storages for the available storages.

For more details about repository usage, see the Repository Storage Service.

Storage Notification

To send Storage notifications you have multiple options:

Using the Abstract Notification

Extend the AbstractNotification::class and implement the ToStorage interface.
The interface requires a toStorageHandler method, which is already provided by AbstractNotification.

You only need to implement the toStorage method, which receives:

• the $recipient entity
• the $channel name
• any autowired services you need

This method must return a Message\StorageInterface instance.

Using the Notification

Storage Recipient

When sending notifications via the Storage Channel, the channel stores the recipient information using the values returned by $recipient->getId() and $recipient->getType().
These values allow you to later fetch or filter notifications for any recipient type your application defines, such as users, system entities, or custom recipient groups.

Accessing Storage Notifications

Once notifications are stored, you can retrieve the notifications using the repository from the channel:

Browser Channel

The Browser Channel stores notification messages in the configured repository so they can later be delivered to the browser (for example via SSE).

Check out the Repository Service to learn more about it.

The storage needs to have the following table columns:

Browser Repository

You may use the provided StorageRepository::class as the repository implementation for storing browser notifications.

To use it, install the storage repository service:

Check out the Storage Service - Storages for the available storages.

For more details about repository usage, see the Repository Storage Service.

Browser Notification

To send Browser notifications you have multiple options.

Using the Abstract Notification

Extend the AbstractNotification::class and implement the ToBrowser interface.
The interface requires a toBrowserHandler method, which is already provided by AbstractNotification.

You only need to implement the toBrowser method, which receives:

• the $recipient entity
• the $channel name
• any autowired services you need

This method must return a Message\BrowserInterface instance.

Using the Notification

Browser Recipient

When sending notifications via the Browser Channel, the channel stores the recipient information using the values returned by $recipient->getId() and $recipient->getType().
These values allow you to later fetch or filter notifications for a specific user, guest, browser ID, or any other recipient type your application defines.

GuestRecipient

A GuestRecipient may be used when sending notifications to anonymous or temporary browser recipients.
If the recipient is a GuestRecipient and defines an expiresAfter value (either an integer in seconds or a DateInterval), the Browser Channel will automatically calculate and store the expires_at timestamp using the injected ClockInterface.

When the id is null, the notification is not tied to a specific user. How this is interpreted is up to your application. For example, you may use it for broadcast-style notifications or identify the browser using a cookie or session value.

For more detail see the Guest Recipient section.

Accessing Browser Notifications

Once notifications are stored, you can retrieve them using the repository provided by the channel:

Channels

Default Channels

Lazy Channels

The creates the channels only on demand.

Queue

You may queue your notification by just adding the parameter:

Requirements

To support queuing notifications you will need to pass a queue handler to the notifier.

Consider using the default queue handler using the Queue Service:

First, install the queue service:

Finally, pass the queue handler to the notifier:

Events

You may listen to the following events if your notifier is configured to support it.

When using the default notifier just pass an event dispatcher.

Credits

• Tobias Strub
• All Contributors
• Symfony