La classe SMailer vous permet, comme son nom l'indique, d'envoyer des mails depuis votre application. 2 modes d'envoi sont disponibles : le premier s'appuie sur la méthode mail() de PHP, le second utilise SMTP.

Votre classe de mailing (nous l'appellerons Notifier) peut être placée où vous le souhaitez dans l'arborescence de votre application (même si le dossier app/models est recommandé), l'essentiel est de lui préciser dans quel dossier trouver les templates :

SMailer::set_template_root('/path/to/mail_templates');

Le principe d'utilisation de SMailer consiste à créer des méthodes définissant les attributs du mail à envoyer. Par exemple :

class Notifier extends SMailer
{
    public function signup_notification($user)
    {
        $this->recipients = $user->email;
        $this->from = 'admin@mydomain.com';
        $this->subject = 'Your account registration';
        $this->body = array('account' => $user);
    }
}

Les attributs disponibles sont les suivants :

• recipients : une ou plusieurs (un tableau) adresses auxquelles délivrer le message
• from : l'adresse de l'expéditeur
• subject : le sujet du message

Comme pour la classe SActionController, à chaque méthode de votre classe doit correspondre un template portant le nom de la méthode. De plus, le template doit posséder, en plus de l'extension .php, une extension précisant le content-type correspondant. Pour l'exemple ci-dessus, si vous souhaitez envoyer un mail en text/plain, le template sera /path/to/mail_templates/signup_notification.plain.php.

Si vous avez affecté un tableau de variables à la propriété $this→body, elles seront accessibles comme variables locales dans le template :

Dear <?= $account->name; ?>,
Thanks for signing up !

Vous pouvez envoyer un mail multipart contenant en plus de la partie text/plain une partie text/html en ajoutant un template supplémentaire /path/to/mail_templates/signup_notification.html.php.

Des méthodes “virtuelles” vous permettent d'envoyer le mail désiré, ou bien de le créer pour l'envoyer plus tard :

$notifier = new Notifier();
$notifier->send_signup_notification($user); // envoie le mail directement
 
$mail = $notifier->prepare_signup_notification($user); // renvoie une instance de SMail
$mail->send();

Vous pouvez ajouter des parties supplémentaires à vos messages multipart très simplement :

class Notifier extends SMailer
{
    public function signup_notification($user)
    {
        $this->recipients = $user->email;
        $this->from = 'admin@mydomain.com';
        $this->subject = 'Your account registration';
 
        $this->parts[] = array('content' => "BEGIN:VCARD\nEND:VCARD\n", 
                               'content_type' => 'text/x-vcard');
    }
}

Vous pouvez de la même façon ajouter des fichiers joints, à partir d'un flux ou non :

class Notifier extends SMailer
{
    public function signup_notification($user)
    {
        $this->recipients = $user->email;
        $this->from = 'admin@mydomain.com';
        $this->subject = 'Your account registration';
 
        $this->attachments[] = array(
            'content' => file_get_contents(dirname(__FILE__).'/image.png'),
            'filename' => 'hello.png', 'content_type' => 'image/png'
        );
 
        $this->attachments[] = array(
            'content' => fopen(dirname(__FILE__).'/image.png', 'r'),
            'filename' => 'world.png', 'content_type' => 'image/png'
        );
    }
}