Email¶

Choisir l’émetteur¶

Quand on envoie des emails de la part d’autre personne, c’est souvent une bonne idée de définir l’émetteur original en utilisant le header Sender. Vous pouvez faire ceci en utilisant sender():

$email = new Email();
$email->sender('[email protected]', 'MyApp emailer');

Configurer les Transports¶

static Cake\Mailer\Email::configTransport($key, $config = null)¶

Les messages d’Email sont délivrés par les transports. Différents transports vous permettent d’envoyer les messages par la fonction mail() de PHP, les serveurs SMTP, ou aucun d’eux ce qui peut être utile pour débugger. La configuration des transports vous permet de garder les données de configuration en dehors du code de votre application et rend le déploiement plus simple puisque vous pouvez simplement changer les données de configuration. Un exemple de configuration des transports ressemblerai à ceci:

use Cake\Mailer\Email;

// Exemple de configuration de Mail
Email::configTransport('default', [
    'className' => 'Mail'
]);

// Exemple de configuration SMTP.
Email::configTransport('gmail', [
    'host' => 'ssl://smtp.gmail.com',
    'port' => 465,
    'username' => '[email protected]',
    'password' => 'secret',
    'className' => 'Smtp'
]);

Vous pouvez configurer les serveurs SSL SMTP, comme Gmail. pour faire ceci, mettez le prefix ssl:// dans l’hôte et configurez le port avec la bonne valeur. Vous pouvez aussi activer TLS SMTP en utilisant l’option tls:

use Cake\Mailer\Email;

Email::configTransport('gmail', [
    'host' => 'smtp.gmail.com',
    'port' => 587,
    'username' => '[email protected]',
    'password' => 'secret',
    'className' => 'Smtp',
    'tls' => true
]);

La configuration ci-dessus va activer la communication TLS pour tous les messages d’email.

Les options de configuration peuvent également être fournies en tant que chaine DSN. C’est utile lorsque vous travaillez avec des variables d’environnement ou des fournisseurs PaaS:

Email::configTransport('default', [
    'url' => 'smtp://[email protected]:[email protected]:465?tls=true',
]);

Lorsque vous utilisez une chaine DSN, vous pouvez définir des paramètres/options supplémentaires en tant qu’arguments de query string.

static Cake\Mailer\Email::dropTransport($key)¶

Une fois configuré, les transports ne peuvent pas être modifiés. Afin de modifier un transport, vous devez d’abord le supprimer et le reconfigurer.

Profiles de Configurations¶

Définir des profiles de délivrance vous permet d’ajouter les configurations habituelles d’email dans des profiles réutilisables. Votre application peut avoir autant de profiles que nécessaire. Les clés de configuration suivantes sont utilisées:

• 'from': Email ou un tableau d’emmeteur. Regardez Email::from().

• 'sender': Email ou un tableau d’émetteur réel. Regardez Email::sender().

• 'to': Email ou un tableau de destination. Regardez Email::to().

• 'cc': Email ou un tableau de copy carbon. Regardez Email::cc().

• 'bcc': Email ou un tableau de copy carbon blind. Regardez Email::bcc().

• 'replyTo': Email ou un tableau de répondre à cet e-mail. Regardez Email::replyTo().

• 'readReceipt': Adresse Email ou un tableau d’adresses pour recevoir un récepissé de lecture. Regardez Email::readReceipt().

• 'returnPath': Adresse Email ou un tableau des adresses à retourner si vous avez une erreur. Regardez Email::returnPath().

• 'messageId': ID du Message de l’e-mail. Regardez Email::messageId().

• 'subject': Sujet du message. Regardez Email::subject().

• 'message': Contenu du message. Ne définissez pas ce champ si vous utilisez un contenu rendu.

• 'priority': Priorité de l’email, exprimée avec un nombre (généralement de 1 à 5, 1 étant la priorité la plus haute).

• 'headers': Headers à inclure. Regardez Email::headers().

• 'viewRender': Si vous utilisez un contenu rendu, définissez le nom de classe de la vue. Regardez Email::viewRenderer().

• 'template': Si vous utilisez un contenu rendu, définissez le nom du template. Regardez Email::template().

• 'theme': Theme utilisé pour le rendu du template. Voir Email::theme().

• 'layout': Si vous utilisez un contenu rendu, définissez le layout à rendre. Si vous voulez rendre un template sans layout, définissez ce champ à null. Regardez Email::template().

• 'viewVars': Si vous utilisez un contenu rendu, définissez le tableau avec les variables devant être rendus dans la vue. Regardez Email::viewVars().

• 'attachments': Liste des fichiers à attacher. Regardez Email::attachments().

• 'emailFormat': Format de l’email (html, text ou both). Regardez Email::emailFormat().

• 'transport': Nom du Transport. Regardez configTransport().

• 'log': Niveau de Log pour connecter les headers de l’email headers et le message. true va utiliser LOG_DEBUG. Regardez aussi Utiliser les Niveaux.

• 'helpers': Tableau de helpers utilisés dans le template email. Email::helpers().

Toutes ces configurations sont optionnelles, excepté 'from'.

Définir les Headers¶

Dans Email, vous êtes libre de définir les headers que vous souhaitez. Si vous migrez pour utiliser Email, n’oubliez pas de mettre le préfixe X- dans vos headers.

Regardez Email::headers() et Email::addHeaders()

Envoyer les Emails Templatés¶

Les Emails sont souvent bien plus que de simples message textes. Afin de faciliter cela, CakePHP fournit une façon d’envoyer les emails en utilisant la view layer de CakePHP.

Les templates pour les emails se placent dans un dossier spécial appelé Email dans le répertoire Template de votre application. Les templates des emails peuvent aussi utiliser les layouts et éléments tout comme les templates normales:

$email = new Email();
$email
    ->template('welcome', 'fancy')
    ->emailFormat('html')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Ce qui est au-dessus utilise src/Template/Email/html/welcome.ctp pour la vue, et src/Template/Layout/Email/html/fancy.ctp pour le layout. Vous pouvez aussi envoyer des messages email templaté multipart:

$email = new Email();
$email
    ->template('welcome', 'fancy')
    ->emailFormat('both')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Ceci utiliserait les fichiers de template suivants:

• src/Template/Email/text/welcome.ctp

• src/Template/Layout/Email/text/fancy.ctp

• src/Template/Email/html/welcome.ctp

• src/Template/Layout/Email/html/fancy.ctp

Quand on envoie les emails templatés, vous avez la possibilité d’envoyer soit text, html soit both.

Vous pouvez définir des variables de vue avec Email::viewVars():

$email = new Email('templated');
$email->viewVars(['value' => 12345]);

Dans votre email template, vous pouvez utiliser ceux-ci avec:

<p>Ici est votre valeur: <b><?= $value; ?></b></p>

Vous pouvez aussi utiliser les helpers dans les emails, un peu comme vous pouvez dans des fichiers de template normaux. Par défaut, seul HtmlHelper est chargé. Vous pouvez chargez des helpers supplémentaires en utilisant la méthode helpers():

$email->helpers(['Html', 'Custom', 'Text']);

Quand vous définissez les helpers, assurez vous d’inclure “Html” ou il sera retiré des helpers chargés dans votre template d’email.

Si vous voulez envoyer un email en utilisant templates dans un plugin, vous pouvez utiliser la syntaxe de plugin familière pour le faire:

$email = new Email();
$email->template('Blog.new_comment', 'Blog.auto_message');

Ce qui est au-dessus utiliserait les templates à partir d’un plugin de Blog par exemple.

Dans certains cas, vous devez remplacer le template par défaut fourni par les plugins. Vous pouvez faire ceci en utilisant les themes en disant à Email d’utiliser le bon theme en utilisant la méthode Email::theme():

$email = new Email();
$email->template('Blog.new_comment', 'Blog.auto_message');
$email->theme('TestTheme');

Ceci vous permet de remplacer le template new_comment dans votre theme sans modifier le plugin Blog. Le fichier de template devra être créé dans le chemin suivant: src/Template/Plugin/TestTheme/Plugin/Blog/Email/text/new_comment.ctp.

Créer des Transports Personnalisés¶

Vous pouvez créer vos transports personnalisés pour intégrer avec d’autres systèmes email (comme SwiftMailer). Pour créer votre transport, créez tout d’abord le fichier src/Mailer/Transport/ExampleTransport.php (où Exemple est le nom de votre transport). Pour commencer, votre fichier devrait ressembler à cela:

namespace App\Mailer\Transport;

use Cake\Mailer\AbstractTransport;
use Cake\Mailer\Email;

class ExampleTransport extends AbstractTransport
{
    public function send(Email $email)
    {
        // Logique d'exécution
    }
}

Vous devez intégrer la méthode send(Email $email) avec votre logique personnalisée. En option, vous pouvez intégrer la méthode config($config). config() est appelée avant send() et vous permet d’accepter les configurations de l’utilisateur. Par défaut, cette méthode met la configuration dans l’attribut protégé $_config.

Si vous avez besoin d’appeler des méthodes supplémentaires sur le transport avant l’envoi, vous pouvez utiliser Cake\Mailer\Email::transportClass() pour obtenir une instance du transport. Exemple:

$yourInstance = $email->transport('your')->transportClass();
$yourInstance->myCustomMethod();
$email->send();

Faciliter les Règles de Validation des Adresses¶

Cake\Mailer\Email::emailPattern($pattern = null)¶

Si vous avez des problèmes de validation lors de l’envoi vers des adresses non conformes, vous pouvez faciliter le patron utilisé pour valider les adresses email. C’est parfois nécessaire quand il s’agit de certains ISP Japonais:

$email = new Email('default');

// Relax le patron d'email, ainsi vous pouvez envoyer
// vers des adresses non conformes
$email->emailPattern($newPattern);