Sender Core

Most, if not all, dynamic sites will have to send transactional e-mails on a regular basis. Within web-framework sending transactional e-mails is abstracted in the abstract SenderCore class. This class has two important static functions and a default implementation for determining the email to send from:

abstract class SenderCore {
    function get_sender_email(): string;
    static function send_raw(string $to, string $subject, string $message): bool;
    static function send(string $template_name, string $to, array $params = array()): bool;
};

By default get_sender_email() will return the e-mail address defined in the configuration at [‘sender_core’][‘default_sender’]. But of course you can override this behaviour in your class extension.

You will have to provide an implementation for SenderCore that uses your preferred transactional e-mail system, and you need to set that in your config.

Postmark implementation

For the base web-framework there is already an implementation for Postmark that can send e.g. e-mail verification mails needed for account registration. This implementation is in web-framework/includes/PostmarkSender.php. So you could use it by doing:

You need to tell the configuration to use this class, by adding or modifying our $site_config in includes/config.php.

$site_config = array(
    'sender_core' => array(
        'handler_class' => 'WebFramework\Core\PostmarkSender',
    ),
    'postmark' => array(
        'api_key' => 'THE_KEY_YOU_GET_FROM_POSTMARK',
        'templates' => array(
            'email_verification_link' => 'THE_TEMPLATE_ID',
        ),
    ),
);

Extending the implementation

But in most cases you’ll want to send different e-mails than the standard transactional e-mails that are provided and implemented in the framework itself.

Let’s make a small extension that can handle another type of transactional e-mails we want to send. Let’s create a file called includes/OwnSenderPostmark.php.

<?php
namespace App\Core;

use WebFramework\Core\PostmarkSender;

class OwnPostmarkSender extends PostmarkSender
{
    protected function data_mail(string $to, array $params): bool
    {
        // Template variables expected
        // * data1
        // * data2
        $from = $this->get_sener_email();

        return $this->send_template_email('YOUR_TEMPLATE_ID', $from, $to, $params);
    }
}
?>

To enable it, we’ll need to add the following to our $site_config array in includes/config.php.

$site_config = array(
    'sender_core' => array(
        'handler_class' => 'App\Core\OwnPostmarkSender',
    ),
);

Now we can send a ‘data’ email from anywhere in the code by calling:

function send(): bool
{
    $params = array(
        'data1' => 'My first data',
        'data2' => 'My seconde data',
    );

    $result = SenderCore::send('data_mail', 'to@unknown.com', $params);
    return $result;
}