Mails

Sending mails in spoova is done through the Mailer class. The functionality of this class is made possible through the combination of third party plugins which are PhpMailer and CssInliner. The Mailer class ensures that mails can be generated from template files and forwarded as mail. It also enables functionalities such as performing dummy tests for mails and also viewing lasting effect of mails.

Installation
In order to use the Mailer class, the PHPMailer and CssInliner libraries must be installed as dependencies. The composer.json file should contain a similar code syntax below can be used to install the supported version of these classes.
  {
    require: {
      'phpmailer/phpmailer' : '^6.0',
      'pelago/emogrifier' : '^6.6'
    }
  }
                    
Once the dependencies are installed through the composer dump-autoload -o, then we need to modify the CssInliner class __construct() method in order for Mailer class to work. This method should be set as public rather than private. Once this is done, we can proceed to set up the configuration files.

Before the Mailer class can be used, there is need to set up the mailer system. Setting up mail system can be addressed in two categories
  • mail configuration setup
  • mail content setup

Setting up mail - config

The mail configuration is done for two systems which are server and headers configurations. Both of this systems can be set up as default (using files) or within the code. It is however advisable to have a default configuration which can be updated when necessary.

Sample Server configuration (server.php)
  <?php

      return [
          'SMTPAuth'   => true,  // Enable SMTP authentication
          'Host'       => 'smtp.mail.com', // Specify main and backup SMTP servers smtp.gmail.com / website hostname
          'Username'   => 'info@site.com', // SMTP username e.g info@site.com..
          'Password'   => '123abc',  // SMTP password  ..
          'SMTPSecure' => 'tls', // Enable TLS encryption, PHPMailer::ENCRYPTION_STARTTLS`PHPMailer::ENCRYPTION_SMTPS`
          'Port'       => 587,   // TCP port to connect to (mostly constant)
      ];


    
Sample Content configuration (headers.php)
  <?php

    // default configuration settings for mail
    $webmail['site']['mail']  = 'info@site.com';  // website mail e.g info@site.com
    $webmail['site']['name']  = 'website';        // mail header name or site name

    //default content settings - should be set later
    $webmail['header'] = ''; // optional - mail title e.g Welcome to ...
    $webmail['body']   = ''; // optional - mail content string or file

    //default user details - should be set later
    $webmail['client']['mail'] = ''; // optional- user email
    $webmail['client']['name'] = ''; // optional- user name 

    
  • In the examples above, we have two files server.php and headers.php. The server.php is used to setup the phpMailer server according to the PHPMailer Documentation. The headers.php is a default file that anchors the PHPMailer headers.
  • The $webmail is a reserved variable that anchors PHPMailers headers' values. Although the $webmail['body'] can be configured here, it is not advisable to do so as the content may change from time to time depending on what type of mail is expected to be sent.
  • The $webmail['client']['mail'] refers to user email to which the mail is expected to be forwarded while the $webmail['client']['name'] is the user name. Both of the $webmail['client'] can easily change, therefore, setting them within the header file is not realistic.
  • After setting up the default parameters, the files can be loaded up when using the Mailer tool. The example below shows how the server.php and headers.php files can be imported.

Sample loading configuration files
  <?php

    use spoova\mi\core\classes\Mailer

    $mail = new Mailer;  // Mailer instantiation

    $mail->server('server');   // add server.php (accepts dots for paths)
    $mail->setup('headers');   // add headers.php (accepts dots for paths)
    
    $mail->authorize(true);   // allow sending of mails 
    
    #update mail headers 
    $mail->sync('header', 'Notice');   // mail subject 
    $mail->sync('client', ['user'=>'foo', 'name' => 'bar']);   // mail subject 

    #send mail
    $mail->sendmail();

    if($mail->sent('online') || $mail->sent('offline')) {

      print 'mail successfully sent';

    }
    

In the example above, $mailer->server() and $mailer->setup() are used to load the default server config and server header respectfully from a config file or array.

The $mail->authorize() either allows or prevents a mail from sending as a means of testing. Setting it as false will prevent the $mailer->sendmail() method from sending out mails when used. This helps to suppress errors especially when working in offline environment. Spoova's online constant can then come into play as online returns true in live or online environment. This can then be rewritten to send mails only in online environment as $mail->authorize(online). For example:

Sample: mail authorize
  <?php

    ...
    
    $mail->authorize(online);   // allow sending of mails online 
    
    #update mail headers 
    $mail->sync('header', 'Notice');   // mail subject 
    $mail->sync('client', ['user'=>'foo', 'name' => 'bar']);   // mail subject 

    #send mail if authorized
    if($mail->authorized()){

      $mailer->sendmail('Hi there, this is a mail');

    } 
    

The $mail->sync() method is used to update the default header configurations just as seen above. It synchronizes new data supplied with the old data set. The mail->authorized() can be used to check if a mail is authorized or not. This may prove useful when handling mails with different configurations or setup.

The last part which is $mailer->sendmail() is used to send a mail content. The content supplied serves as the body of the mail headers. Although a string can be forwarded from the sendmail option. It is preferred that this should be a file instead. The Mailer system allows that html mail pages can be sent. By default, it also accepts embeded css stylesheets. This means that an html page can be forwarded as a mail. However, it is important to stick with either embedded or inline css when writing mail pages or mail template pages to prevent undesired results.

Sample: template content loading
  <?php

    ...
      
    if($mail->authorized()){

      $mailer->sendmail( Res::markup('mail-temp.feedback', fn() => compile()) );

    } 
    


Since the Res::markup() prevents compile() from displaying a content, but instead returns the content of a rex file, a template processed page can be forwarded as a mail. However, the mailer tool has its internal way of handling template files. In order to send a raw file, The $mailer->content('filename.php') must be set where filename.php is the name or path of the file. Supported files include xml, txt, html and php. You can learn more about this on the templating page.