Envoi de mail avec BowPHP

Introduction

Envoyer des emails dans une application est monnaie courante. BowPHP intègre un système d'envoi d'email facile à utiliser. Vous pouvez utiliser ce système à travers plusieurs pilotes communément appelés drivers :

• smtp — Envoi direct via un serveur SMTP
• ses — Envoi via Amazon SES
• mail — Utilise la fonction mail() native de PHP
• log — Écrit le mail dans les logs (pratique en développement)

Configuration

Vous trouverez la configuration dans le fichier config/mail.php qui est relativement simple. Les options sont toutes commentées.

Driver SES

Installez le package aws/aws-sdk-php si vous voulez utiliser ses comme driver de mail.

composer require aws/aws-sdk-php

Changer de driver à l'exécution

use Bow\Mail\Mail;

Mail::setDriver('log');     // bascule tous les envois sur le log
Mail::setDriver('smtp');    // retour au driver configuré

Utilisation

Pour utiliser le service, appelez la classe Bow\Mail\Mail. Elle expose les méthodes statiques suivantes :

Méthode	Usage
send($view, $data, $cb)	Envoie un email basé sur une vue
raw($to, $subject, $message, $headers = [])	Envoie un texte brut
queue($view, $data, $cb)	Met l'envoi en file d'attente
queueOn($queue, $view, $data, $cb)	File d'attente nommée
later($delay, $view, $data, $cb)	Envoi différé (en secondes)
laterOn($delay, $queue, $view, $data, $cb)	Différé sur file nommée
setDriver($driver)	Bascule de driver à la volée

La méthode send

send permet d'envoyer des emails basés sur une vue.

Prototype

Mail::send(string $view, array|callable $data, ?callable $cb = null): bool

Paramètre	Type	Description
$view	string	Le nom de la vue à utiliser
$data	array ou callable	Données passées à la vue. Si vous l'omettez et passez le constructeur directement en 2e argument, c'est aussi valable.
$cb	?callable	Constructeur de l'enveloppe (voir Envelop ci-dessous)

Le callback reçoit une instance de Bow\Mail\Envelop qui permet d'ajouter le destinataire, l'objet, les pièces jointes, l'expéditeur, etc.

Exemple

Considérons la vue email-view.tintin.php :

templates/email-view.tintin.php

Bonjour {{ $name }},

Nous vous informons que votre compte vient d'être crédité de 100.000.000 F.

Cordialement,

Le code qui envoie le mail :

use Bow\Mail\Mail;
use Bow\Mail\Envelop;

$data = ['name' => 'Franck'];

Mail::send('email-view', $data, function (Envelop $envelop) {
  $envelop->to('info@exemple.com');
  $envelop->subject('Paiement !');
  $envelop->from('info@exemple.com', 'Bow');
});

Forme courte (sans données pour la vue) :

Mail::send('email-view', function (Envelop $envelop) {
  $envelop->to('info@exemple.com')
          ->subject('Bonjour')
          ->from('info@exemple.com', 'Bow');
});

API de Envelop

L'objet Bow\Mail\Envelop accumule les destinataires, en-têtes et le corps du message. Toutes ses méthodes retournent $this, ce qui permet le chaînage.

Destinataires

$envelop->to('info@exemple.com');               // un destinataire
$envelop->to(['a@x.com', 'b@x.com']);            // plusieurs destinataires
$envelop->addCc('cc@x.com', 'Nom CC');
$envelop->addBcc('bcc@x.com');
$envelop->addReplyTo('reply@x.com');
$envelop->addReturnPath('bounces@x.com');

Aliases

Les méthodes courtes cc(), bcc(), replyTo(), returnPath() sont des alias de leurs versions addCc/addBcc/addReplyTo/addReturnPath et ont la même signature.

Sujet et expéditeur

$envelop->subject('Objet du message');
$envelop->from('noreply@x.com', 'Mon App');

Corps du message

$envelop->html('<h1>Bonjour</h1>');   // contenu HTML (type text/html)
$envelop->text('Bonjour');             // contenu texte brut
$envelop->view('emails.welcome', ['user' => $user]); // rend une vue

En-têtes personnalisés

$envelop->withHeader('X-Custom-Header', 'valeur');

Pièces jointes

$envelop->addFile('/chemin/vers/fichier.pdf');

Priorité

// Priorité X-Priority : 1 (highest) à 5 (lowest)
$envelop->setPriority(1);     // ou $envelop->addPriority(1)

La méthode raw

raw permet d'envoyer un message brut (sans vue) :

Mail::raw(string|array $to, string $subject, string $data, array $headers = []): mixed

Paramètre	Type	Description
$to	string|array	Email(s) du destinataire
$subject	string	Objet du mail
$data	string	Corps du message
$headers	array	En-têtes additionnels

use Bow\Mail\Mail;

Mail::raw(
  'hello@exemple.com',
  'Hello, world',
  "C'est juste un email de test"
);

Envoi en file d'attente

Pour ne pas bloquer la requête HTTP, mettez l'envoi en file d'attente. La signature (view, data, cb) est identique à send.

use Bow\Mail\Mail;
use Bow\Mail\Envelop;

// File par défaut
Mail::queue('email-view', ['name' => 'Franck'], function (Envelop $e) {
  $e->to('info@exemple.com')->subject('Bonjour')->from('app@x.com');
});

// File nommée (priorité haute par exemple)
Mail::queueOn('high', 'email-view', $data, $callback);

// Envoi différé de 60 secondes
Mail::later(60, 'email-view', $data, $callback);

// Différé sur file nommée
Mail::laterOn(3600, 'mails', 'email-view', $data, $callback);

Worker requis

N'oubliez pas qu'un worker doit tourner (php bow run:worker) pour traiter les jobs en file.

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.