Create E-Mail Notification Controller

Apex has a built-in notifications system that allows e-mails to be automatically triggered when pre-defined actions occur (eg. user is created), which are managed via the Settings->Notifications menu of the administration panel. This page goes through how to develop an e-mail controller that will allow the administrator to define desired e-mail notifications to be sent when certain actions occurred.

# You may create a new controller through the opus email-notification CLI command, for example:

apex opus email-controller MyPackage/Controllers/myPackageNotificationController

The above will create a new file located at /src/MyPackage/Controllers/MyPackageNotificationController.php. This PHP class contains one property named $title, which is the name displayed within the create notification select list in the Settings->Notifications menu.

getConditionFormFields()

Upon creating an e-mail notification via the Notification->Settings menu, on the second page after selecting the notification type, the top section allows the user to specify the conditional information. These are variables you as the developer define, allowing the user to define exactly which action will trigger the e-mail notification to be sent. See below for actually processing e-mail notifications.

This method provides an instance of the FormBuilder class as is the standard form builder within Apex. For full information, please visit the FOorm Component page of the documentation.

getMergeFields()

When defining the contents of an e-mail notification, a select list of available merge variables is displayed, which contains a list of all fields the e-mail message can be personalized with.

This method allows you to add additional merge fields to that select list. Simply return an associative array, the key being the display name of the merge fields and the value being an associative array of the merge field itself as the key, and the name to display within the web browser as value. An example is shown in the default PHP class.

getMergeVars(string $uuid, array $data)

Accompanied by the above getMergeFields() method, this method is called while an e-mail is being sent and collects the necessary personalized data for the fields defined within getMergeFields.

The method accepts the $dat associatve array that is passed upon e-mail notifications being processed, which should contain any necessary unique ID numbers or similar in order to retrieve the necessary information. from. A simple associate array is returned, the keys being the merge fields themselves as defined within getMergeFields() and the values being what to personalize the merge field with.

getAvailableSenders( / getAvailableRecipients()

Upon creating an e-mail notification via the administration panel, the system will also prompt for a sender and recipient. By default, these two select lists re populated with each administrator and "User".

These two methods allow you to add additional options into the two select lists. If there are no additional snders / recipients simply leave as is and return null. Otherwise, return an associative array of the additional options, key being for the back-end software, and value being what's displayed within the web browser.

getSender(string $sender, UserInterface $user, array $data = []):?EmailContact

Only applicable if the getAvailableSenders() method returns an associative array of custom senders instead of null. If the $sender parameter is one of the custom defined senders, this method should return an instance of the EmailContact class, and null otherwise.

getRecipients(string $recipient, UserInterface $user, array $data = []):?EmailContactCollection

Only applicable if the getAvailableRecipients() method returns an associative array of custom recipients instead of null. If the $recipient parameter is one of the custom defined recipients, this method should return an instance of the EmailContactCollection class, which is basically an array of EmailContact objects. Otherwise, this method should return null.

getReplyTo() / GetCc() / getBcc()

As the method names imply, if the e-mail notifications should provide any e-mail addresses within the reply-to, cc or bcc e-mail headers, return them within these methods.

Sending E-Mail Notifications

Once the e-mail notification controller has been developed, you will need to trigger the processing of e-mail notifications. This is done by pulling the App\Webapp\Notifications\Notifications class in via dependancy injection, and executing the Notifications::process() method.

Below shows an example that processes all pending e-mail notifications for the App\MyPackage\Controllers\myPackageNotificationController class:

<?php
declare(strict_types=1);

namespace App\MyPackage;

use App\Webapp\Notifications\Notifications;
use App\MyPackage\Controllers\myPackageNotificationController;
use App\Users\User;

/**
 * Test class
 */
class TestClass
{

    /**
    * Create item
     */
    public function create(User $user):void
    {

        // Set condition
        $condition = [
            'action' => 'create'
        ];

        // Process e-mail notifications
        $this->notifications->process(myPackageNotificationController::class, $user->getUuid(), $condition);

    }

}

The Notifications::process() method takes in four arguments, the full class name of the e-mail controller to process notifications for, an optional UUID of the user notifications are being processed for / on, an optinoal condition array that must match the conditional variables the notification was created with, and an optional data array containing any additional information necessary to personalize the e-mail message (eg. order id#, etc).

The systemw ill go through all notifications created under the specified e-mail controller, then check the passed condition array against the condition the notification was created with. If it matches, the e-mail will be automatically sent out to the necessary recipients.

zzzzzzzzzzzz