rias / craft-notifications
Send notifications across a variety of delivery channels, including mail and Slack. Notifications may also be stored in a database so they may be displayed in your web interface.
Installs: 22 586
Dependents: 2
Suggesters: 0
Security: 0
Stars: 55
Watchers: 6
Forks: 8
Type:craft-plugin
Requires
- php: ^8.0.2
- craftcms/cms: ^4.0.0-beta.1
- guzzlehttp/guzzle: ^7.0
- nesbot/carbon: ^2.19
Requires (Dev)
- craftcms/phpstan: dev-main
- v4.x-dev
- 4.1.2
- 4.1.1
- 4.1.0
- 4.0.0
- 4.0.0-RC1
- v1.x-dev
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.6
- 1.1.5.2
- 1.1.4
- 1.1.3
- 1.1.1
- 1.1.0
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.1
- 1.0.0
- dev-v4-develop
- dev-dependabot/composer/guzzlehttp/psr7-2.5.0
- dev-renovate/configure
- dev-v1-develop
- dev-master
- dev-dependabot/composer/tightenco/collect-tw-7.12
- dev-dependabot/composer/ramsey/uuid-tw-4.0
- dev-develop
This package is auto-updated.
Last update: 2024-09-12 14:07:48 UTC
README
Notifications plugin for Craft CMS 3.x
Send notifications across a variety of delivery channels, including mail and Slack. Notifications may also be stored in a database so they may be displayed in your web interface.
- Installation
- Introduction
- Sending notifications
- Database notifications
- Delete notifications
- Mail notifications
- Slack notifications
- Notification events
- Custom channels
Support Open Source. Buy beer.
This plugin is licensed under a MIT license, which means that it's completely free open source software, and you can use it for whatever and however you wish. If you're using it and want to support the development, buy me a beer over at Beerpay!
Requirements
This plugin requires Craft CMS 3.1.0 or later.
Installation
To install the plugin, follow these instructions.
-
Open your terminal and go to your Craft project:
cd /path/to/project
-
Then tell Composer to load the plugin:
composer require percipioglobal/craft-notifications
-
In the Control Panel, go to Settings → Plugins and click the “Install” button for Notifications.
-
Copy the
config.php
file toconfig/notifications.php
in your application. -
Make sure your notifications are autoloaded by adding the following to your
composer.json
and runnningcomposer dump -o
"autoload": {
"psr-4": {
"app\\notifications\\": "./notifications"
}
},
Introduction
Typically, notifications should be short, informational messages that notify users of something that occurred in your application. For example, if you are writing a billing application, you might send an "Invoice Paid" notification to your users via the email and SMS channels.
Creating notifications
Each notification is represented by a single class (stored in the notifications
directory of your application). You will have to create it manually or it will be created for you when you run the notifications/make
command:
./craft notifications/make BlogPostAdded
This command will place a fresh notification class in your notifications
directory. Each notification class contains a via
method and a variable number of message building methods (such as toMail
or toDatabase
) that convert the notification to a message optimized for that particular channel.
Sending notifications
Notifications can be sent in two ways, either from the configuration file when an event
is fired, or from your own plugins.
First, let's show how you configure sending a notification when for example a new blogpost is added:
<?php return [ 'notifications' => [ [ 'class' => \craft\elements\Entry::class, 'event' => \craft\elements\Entry::EVENT_AFTER_SAVE, 'notification' => \app\notifications\BlogPostAdded::class, ], ], ];
Here we're listening from the EVENT_AFTER_SAVE
event on the Entry
class of Craft which will cause our notification to be triggered every time we save an entry.
In our BlogPostAdded
class we can then use the via
function to determine if and how we want to send the notification:
/** * Get the notification's delivery channels. * * @return array */ public function via() { $entry = $this->event->sender; if ($entry->section->handle === 'blog' && $this->event->isNew) { return [ 'database' => Craft::$app->getUsers()->getUserByUsernameOrEmail('hello@percipio.london'), ]; } return []; }
We know the event is an ElementEvent
, which contains the sender
and an isNew
property, using this information we can determine that we only want to send a notification when the entry is from the blog
section and it's a new Entry.
Sending a notification from a plugin
From a plugin, you can use the notificationsService
to send you own notifications.
use percipioglobal\notifications\Notifications; use app\notifications\BlogPostAdded; Notifications::getInstance()->notificationsService->send(new BlogPostAdded());
Database notifications
To save a notification in the database for later retrieval, make sure your via
method returns the database
key with a User
object as value.
return [ 'database' => Craft::$app->getUsers()->getUserByUsernameOrEmail('hello@percipio.london'), ];
When using the database
notification channel, your Notification class should define a toDatabase
or toArray
function.
This can be as simple as:
public function toDatabase() { return ArrayHelper::toArray($this); }
When retrieving the notifications from the database in your templates, the notification will contain the data that is passed here.
Retrieving notifications
The notifications plugin provides a template variable to retrieve notifications and mark them as read.
Let's see how we can loop over the notifications, this automatically uses the current logged in user to find notifications for:
{% for notification in craft.notifications.unread %} {# The notification object contains all the data from the toDatabase or toArray function on your notification class #} {% endfor %}
You can also retrieve the notifications through the notificationsService
use percipioglobal\notifications\Notifications; // All unread notifications Notifications::getInstance()->notificationsService->getAllUnread(); // All read notifications Notifications::getInstance()->notificationsService->getAllRead(); // All notifications Notifications::getInstance()->notificationsService->getAll();
Marking notifications as read
To mark notifications as read, we can use the Twig variable or the notificationsService
as well. This function expects an array of notifications.
{% for notification in craft.notifications.unread %} {{ craft.notifications.markAsRead(notification) }} {% endfor %}
use percipioglobal\notifications\Notifications; Notifications::getInstance()->notificationsService->markAsRead($notification);
Delete read notifications
To keep your database clean and lean, you can delete the read notifications older than a given time frame. The default time is set to -1 month
. If you want a custom time frame, provide the date within the strtotime PHP restrictions.
./craft notifications/remove-notifications/index --time="-3 months"
Mail notifications
To configure a notification to be sent as an email, make sure your via
method on the Notification class returns a key with mail
:
return [ 'mail' => 'hello@percipio.london', ];
If a notification supports being sent as an email, you should define a toMail
method on the notification class. This method will receive a $notifiable
object that contains everything you defined in your via
method.
The toMail
function should return a craft\mail\Message
instance. You may also return an array of craft\mail\Message
instances if you wish to send multiple emails. Let's take a look at an example toMail method:
public function toMail($notifiable) { $title = $this->event->sender->title; $message = new Message(); $message->setTo($notifiable); $message->setSubject("A new blogpost was added"); $message->setHtmlBody(" <p>Hey there!</p> <p>A new blogpost was added with the title {$title}</p> "); return $message; }
Slack notifications
You will need to configure an "Incoming Webhook" integration for your Slack team. This integration will provide you with a URL you may use when defining your via
function.
return [ 'slack' => '<YOUR_WEBHOOK_URL>', ];
The implementation and documentation are mostly based on Laravel Notifications.
Formatting Slack notifications
If a notification supports being sent as a Slack message, you should define a toSlack
method on the notification class. This method should return a percipioglobal\notifications\messages\SlackMessage
instance. Slack messages may contain text content as well as an "attachment" that formats additional text or an array of fields. Let's take a look at a basic toSlack
example:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack() { return (new SlackMessage) ->content('A new blogpost was added!'); }
Customizing The Sender & Recipient
You may use the from
and to
methods to customize the sender and recipient. The from
method accepts a username and emoji identifier, while the to
method accepts a channel or username:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack($notifiable) { return (new SlackMessage) ->from('Ghost', ':ghost:') ->to('#other') ->content('This will be sent to #other'); }
You may also use an image as your logo instead of an emoji:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack($notifiable) { return (new SlackMessage) ->from('Laravel') ->image('https://yoursite.com/favicon.png') ->content('This will display your logo next to the message'); }
Slack attachments
You may also add "attachments" to Slack messages. Attachments provide richer formatting options than simple text messages. In this example, we will send an error notification about an exception that occurred in an application, including a link to view more details about the exception:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack($notifiable) { $url = url('/exceptions/'.$this->exception->id); return (new SlackMessage) ->error() ->content('Whoops! Something went wrong.') ->attachment(function ($attachment) use ($url) { $attachment->title('Exception: File Not Found', $url) ->content('File [background.jpg] was not found.'); }); }
The example above will generate a Slack message that looks like the following:
Attachments also allow you to specify an array of data that should be presented to the user. The given data will be presented in a table-style format for easy reading:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack($notifiable) { $url = url('/invoices/'.$this->invoice->id); return (new SlackMessage) ->success() ->content('One of your invoices has been paid!') ->attachment(function ($attachment) use ($url) { $attachment->title('Invoice 1322', $url) ->fields([ 'Title' => 'Server Expenses', 'Amount' => '$1,234', 'Via' => 'American Express', 'Was Overdue' => ':-1:', ]); }); }
The example above will generate a Slack message that looks like the following:
Markdown Attachment Content
If some of your attachment fields contain Markdown, you may use the markdown
method to instruct Slack to parse and display the given attachment fields as Markdown formatted text. The values accepted by this method are: pretext
, text
, and / or fields
. For more information about Slack attachment formatting, check out the Slack API documentation:
/** * Get the Slack representation of the notification. * * @param mixed $notifiable * @return SlackMessage */ public function toSlack($notifiable) { $url = url('/exceptions/'.$this->exception->id); return (new SlackMessage) ->error() ->content('Whoops! Something went wrong.') ->attachment(function ($attachment) use ($url) { $attachment->title('Exception: File Not Found', $url) ->content('File [background.jpg] was *not found*.') ->markdown(['text']); }); }
Notification Events
When a notification is sent, there are two events that get triggered, the NotificationsService::EVENT_BEFORE_SEND
and NotificationsService::EVENT_AFTER_SEND
which send a percipioglobal\notifications\events\SendEvent
event.
The sendEvent
contains the following properties:
/** * @var mixed The notifiable. */ public $notifiable; /** * @var NotificationsRecord The notification about to be sent. */ public $notification; /** * @var string The channel on which the notification is about to be sent. */ public $channel; /** * @var bool Whether we send the notification */ public $sendNotification = true; /** * @var mixed The response after sending the event */ public $response = null;
The sendNotification
property can be changed when listening for EVENT_BEFORE_SEND
to prevent the notification from being sent. The response
property is only set on the EVENT_AFTER_SEND
event.
Custom channels
Craft Notifications ships with three channels (database, mail & Slack), but you may want to write your own drivers to deliver notifications via other channels. We make this simple by exposing an event where you can register new channels.
Let's explore how we'd register a voice
channel:
Event::on( NotificationsService::class, NotificationsService::EVENT_REGISTER_CHANNELS, function (RegisterChannelsEvent $event) { $event->channels[] = [ 'voice' => function () { return new VoiceChannel(); }, ]; } );
Your VoiceChannel
class would then look like this:
<?php namespace app\channels; use percipioglobal\notifications\models\Notification; class VoiceChannel { /** * Send the given notification. * * @param mixed $notifiable * @param \percipioglobal\notifications\models\Notification $notification * @return void */ public function send($notifiable, Notification $notification) { $message = $notification->toVoice($notifiable); // Send notification to the $notifiable... } }
Once your notification channel class has been defined, you may simply add the key to your via
method in your notifications. What the value should be depends on the implementation of your channel.
<?php namespace App\Notifications; use app\channels\VoiceChannel; use app\channels\messages\VoiceMessage; use percipioglobal\notifications\models\Notification; class InvoicePaid extends Notification { /** * Get the notification channels. * * @param mixed $notifiable * @return array|string */ public function via($notifiable) { return [ 'voice' => '<YOUR_DESTINATION>', ]; } /** * Get the voice representation of the notification. * * @param mixed $notifiable * @return VoiceMessage */ public function toVoice($notifiable) { // ... } }
The implementation of channels are very alike to how it's done with Laravel, if you need a specific channel there's a big chance you'll find one at Laravel Notification Channels that only needs a few implementation changes.
The functionality of adding a channel is very easily extracted to a plugin, if you implement a custom one, please consider sharing them with the community.
Brought to you by Percipio Global Ltd.