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:

.. code-block:: php

    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*.

.. code-block:: 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*.

.. code-block:: 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*.

.. code-block:: 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:

.. code-block:: php

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

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