Notifications

Qore comes with the ability to let administrators manage notification classes.

Getting started

Preparing the resources

Prepare Qore Resources and Models to make them 'manageable' through settings by:

• Implementing the \Qore\System\Notifications\Notifiable trait on the resource.
• Implementing the \Illuminate\Notifications\Notifiable trait on the model.

Let's make the ContactResource manageable:

use Qore\System\Notifications\Notifiable;

class ContactResource extends QoreResource
{
    use Notifiable;
}

use Illuminate\Notifications\Notifiable;

class Contact extends Model
{
    use Notifiable;
}

The ContactResource will now show up in the notification settings:

Creating a Qore Notification

First create a Laravel notification using the artisan command.

php artisan make:notification PodcastProcessed

Let the class extend the QoreNotification class. Make sure to implement the missing method stubs.

• getIdentifier - The identifier of the notification. This will be used as a backup to identify the notification in the database.
• getLabel - The label of the notification.
• getDescription - The description of the notification.
• getSupportedNotifiableResources - The supported notifiable resources.

You can omit/remove most methods like via etc.

A minimal managed QoreNotification would look like this:

namespace App\Notifications;

use Qore\System\Notifications\QoreNotification;
use App\Models\Tenant\Podcast;

class PodcastProcessed extends QoreNotification
{
    public function __construct(protected Podcast $podcast)
    {
        //
    }

    public static function getIdentifier(): string
    {
        return 'podcast-processed';
    }

    public static function getLabel(): string
    {
        return __('notifications.podcast_processed.label');
    }

    public static function getDescription(): string
    {
        return __('notifications.podcast_processed.description');
    }

    public static function getSupportedNotifiableResources(): array
    {
        return [
            'contacts',
            'users',
            'tenants',
        ];
    }
}

Setting supported notifiable resources

The getSupportedNotifiableResources method returns an array of the supported notifiable resources. In the example above we returned ['contacts', 'users', 'tenants'] which means that the notification will show under the contact, user and tenant resources in the notification settings.

Setting the managed channels

By default administrators will be able to manage all manageable channels on the notification (later more on this). You can change this behaviour by overriding the getManagedChannels method to your resource:

The following example will only make the qore-mail channel manageable:

class PodcastProcessed extends QoreNotification
{
    public static function getManagedChannels(): array
    {
        return [
            'qore-mail',
        ];
    }
}

Sending notifications

Sending Qore Notifications is no different then sending regular Laravel notifications. You can use the notify method on the model to send a notification:

$notification = new PodcastProcessed($podcast);

$contact->notify($notification);

When the notification is send, Laravel will get the route from the model using routeNotificationFor<Channel> method and use that to send the notification.

In the background Qore will check if the notification should actually be send to the model. By comparing notification settings and preferences (if applicable)

Allowing channel template management

A Qore Notification Channel might accept custom templates. For example a user can create a MailTemplate for QoreMail notifications.
Setting up templates for mailing will be explained below. Refer to the documentation of other channels for more information, like Slack.

Setting up Qore MailTemplates

To accept MailTemplates on notifications you need to

• Implement the \Qore\System\Mailing\Notifications\HasQoreMailTemplate trait.
• Return true from the acceptsTemplatesForQoreMail method.

use Qore\System\Mailing\Notifications\HasQoreMailTemplate;

class PodcastProcessed extends QoreNotification
{
    use HasQoreMailTemplate;
    ...
    public static function acceptsTemplatesForQoreMail(): bool
    {
        return true;
    }
}

Administrators will be able to create mail templates and select them in the notification settings.

To set a default template return the template identifier from getDefaultTemplateIdentifierForQoreMail.
This identifier will be used to try and find a Qore MailTemplate if no template is selected.

use Qore\System\Mailing\Notifications\HasQoreMailTemplate;

class PodcastProcessed extends QoreNotification
{
    public static function getDefaultTemplateIdentifierForQoreMail(): string|int|null
    {
        return 'podcast-processed';
    }
}

If the MailTemplate has a variable list that needs a Model you'd need to set it in the Notification:

use Qore\System\Mailing\Notifications\HasQoreMailTemplate;

class PodcastProcessed extends QoreNotification
{
    ...
    public function __construct(protected Podcast $podcast)
    {
        $this->qoreMailVariableListModelId = $podcast->id;
    }
}

Or set the model from outside the class:

$notification = (new MyNotification)
    ->setQoreMailVariableListModel($podcast->id);

Sending templates

If the settings for a Qore MailTemplate are set, the selected template will be rendered before sending the notification to it's receivers.

Full ProcessPodcast notification

<?php

namespace App\Notifications;

use Qore\Messagebird\Notifications\Traits\HasMessagebirdSmsTemplate;
use Qore\Messagebird\Notifications\Traits\HasMessagebirdWhatsappTemplate;
use Qore\Slack\Notifications\Traits\HasSlackTemplate;
use Qore\System\Mailing\Notifications\HasQoreMailTemplate;
use Qore\System\Notifications\QoreNotification;
use App\Models\Tenant\Podcast;

class PodcastProcessed extends QoreNotification
{
    use HasMessagebirdSmsTemplate,
        HasMessagebirdWhatsappTemplate,
        HasQoreMailTemplate,
        HasSlackTemplate;

    public function __construct(protected Podcast $podcast)
    {
        $this->slackVariableListModelId
            = $this->qoreMailVariableListModelId
            = $this->messagebirdSmsVariableListModelId
            = $this->messagebirdWhatsappVariableListModelId
            = $this->podcast->getKey();
    }

    public static function getManagedChannels(): array
    {
        return [
            'qore-mail',
            'messagebird-sms',
            'messagebird-whatsapp',
            'slack',
        ];
    }

    public static function getIdentifier(): string
    {
        return 'podcast-processed';
    }

    public static function getLabel(): string
    {
        return __('notifications.podcast_processed.label');
    }

    public static function getDescription(): string
    {
        return __('notifications.podcast_processed.description');
    }

    public static function getDefaultTemplateIdentifierFor(string $channel): string|int|null
    {
        // Every channel that supports templates will use the same identifier.
        return 'podcast-processed';
    }

    public static function getSupportedNotifiableResources(): array
    {
        return [
            'users',
            'tenants',
            'contacts',
        ];
    }
    
    public static function acceptsTemplatesFor(string $channel): bool
    {
        // We accept template management for all known channels
        return true;
    }
}