Download the PHP package snebes/notifications-bundle without Composer
On this page you can find all versions of the php package snebes/notifications-bundle. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package notifications-bundle
snebes/notifications-bundle
The snebes/notifications-bundle
provides a snebes/notifications integration for your Symfony projects.
Notifications is an abstraction layer, inspired by Laravel, which allows you to easily add support for email and web-interface messaging.
A demo Symfony application with this bundle pre-installed is available. Check out snebes/notifications-demo.
Prerequisites
This bundle requires Symfony 3.4+ and utilized doctrine/doctrine-bundle
and symfony/swiftmailer-bundle
to provide notifications.
Installation
Add snebes/notifications-bundle
to your composer.json
file:
Register the bundle:
Symfony 3:
Register bundle in app/AppKernel.php
:
Symfony 4:
Register bundle in config/bundles.php
. Flex will do this for you.
Creating Notifications
Each notification is represented by a single class (typically stored in the src/Notifications
directory).
Don't worry if you don't see this directory in your application, it will be created for you when you run the make:sn:notification command:
This command will place a new notification class in your src/Notifications
directory.
Each notification class contains a via
method and a variable number of message building methods (such as toMail
or toArray
) that convert the notification to a message optimized for that particular channel.
Sending Notifications
Notifications may be sent by the NotificationSender
service.
This component provides helpers to enable classes, such as the above User
class, to accept notifications.
NotifiableTrait
adds the ability for any class to receive a database or mail message.
To reference the database notifications from the entity, a $notification
field will need to be configured for Doctrine to map the relationship.
Specifying Delivery Channels
Every notification class has a via
method that determines on which channels the notification will be delivered.
Notifications may be sent on the mail
and database
channels.
The via
method receives a NotifiableInterface
instance, which will be an instance of the class to which the notification is being sent.
You may use the NotifiableInterface
to determine which channels the notification should be delivered on:
Mail Notifications
If a notification supports being sent as an email, the class should implement MailableInterface
and define a toMail
method.
This method will receive a NotifiableInterface
entity and should return a SN\Notifications\Contracts\EmailInterface;
instance.
Let's take a look at an example toMail
method:
In this example, we created an email with a subject and text line.
These methods provided by the Email
object make it simple and fast to format small transactional emails.
The mail channel will automatically fill in the to
address for each NotifiableInterface
.
Customizing The Recipient
When sending notifications via the mail
channel, the notification system will automatically look for an email
property on your NotifiableInterface
entity.
You may customize which email address is used to deliver the notification by defining a routeNotificationForMail
method on the entity:
Database Notifications
Prerequisites
The database
notification channel stores the notification information in a database table.
This table will contain information such as the notification type as well as custom JSON data that describes the notification.
You can query the table to display the notifications in your application's user interface.
But, before you can do that, you will need to create a database table to hold your notifications.
You may use the doctrine:migration:diff
command to generate a migration with the proper table schema:
Formatting Database Notifications
If a notification supports being stored in a database table, the class should implement ArrayableInterface
and define a toArray
method.
This method will receive a NotifiableInterface
entity and should return a plain PHP array.
The returned array will be encoded as JSON and stored in the data column of your notifications table.
Let's take a look at an example toArray
method:
Accessing The Notifications
Once notifications are stored in the database, you need a convenient way to access them from your notifiable entities.
The NotifiableTrait
, which is included in this component, includes helpers for a $notifications relationship that returns the notifications for the entity.
To fetch notifications, you may used the getNotifications()
, getUnreadNotifations()
and getReadNotifications()
methods.
By default, notifications will be sorted by the createdAt
timestamp:
Marking Notifications As Read
Typically, you will want to mark a notification as "read" when a user views it.
The SSN\Bundle\NotificationsBundle\Entity\Notification
entity class provides a setReadAt
method, which updates the readAt
column on the notification's database record:
Notification Events
When a notification is sent, the component dispatches multiple events which you can use to modify how the notification is handled.
NotificationEvents::SENDING
Event Class: SN\Notifications\Event\NotificationSendingEvent
This event is dispatched before the Notification is sent. It's useful to add more information to the Notification or stop a Notification from being sent.
Execute this command to find out which listeners are registered for this event and their priorities:
NotificationEvents::SEND
Event Class: SN\Notifications\Event\NotificationSendEvent
This event is dispatched to send the Notification. It's main use is to send the Notification to the desired Channel, which is how Channels are used internally in this component.
Execute this command to find out which listeners are registered for this event and their priorities:
NotificationEvents::SENT
Event Class: SN\Notifications\Event\NotificationSentEvent
This event is dispatched after the Notification is successfully sent. It's useful to perform tasks on Notifications that have been sent.
Execute this command to find out which listeners are registered for this event and their priorities:
NotificationEvents::EXCEPTION
Event Class: SN\Notifications\Event\NotificationExceptionEvent
This event is dispatched as soon as an error occurs during the handling of the Notification. It's useful to recover from errors or modify the Notification.
Execute this command to find out which listeners are registered for this event and their priorities:
Custom Channels
This component ships with a handful of notification channels, but you may want to write your own to deliver notifications via other methods.
The dispatched notification events makes it simple.
To get started, define a class that listens or subscribes to the NotificationEvents::SEND
event.
Once your notification channel class has been defined, you may return the class name from the via
method of any of your notifications.