Mail

Envoi de
Emails

Envoi de courriels

Allez-vous envoyer des courriels tels que des bulletins d'information ou des confirmations de commande ? Nette Framework fournit les outils nécessaires avec une très belle API. Nous allons vous montrer :

  • comment créer un email, y compris les pièces jointes
  • comment l'envoyer
  • comment combiner des e-mails et des modèles

Installation

Téléchargez et installez le paquet en utilisant Composer:

composer require nette/mail

Création de courriels

Le courrier électronique est un objet Nette\Mail\Message:

$mail = new Nette\Mail\Message;
$mail->setFrom('John <john@example.com>')
	->addTo('peter@example.com')
	->addTo('jack@example.com')
	->setSubject('Order Confirmation')
	->setBody("Hello, Your order has been accepted.");

Tous les paramètres doivent être encodés en UTF-8.

En plus de spécifier les destinataires avec la méthode addTo(), vous pouvez également spécifier le destinataire de la copie avec addCc(), ou le destinataire de la copie cachée avec addBcc(). Toutes ces méthodes, y compris setFrom(), acceptent le destinataire de trois manières :

$mail->setFrom('john.doe@example.com');
$mail->setFrom('john.doe@example.com', 'John Doe');
$mail->setFrom('John Doe <john.doe@example.com>');

Le corps d'un courriel écrit en HTML est transmis à l'aide de la méthode setHtmlBody():

$mail->setHtmlBody('<p>Hello,</p><p>Your order has been accepted.</p>');

Vous n'avez pas besoin de créer une alternative textuelle, Nette la génère automatiquement pour vous. Et si l'email n'a pas de sujet défini, celui-ci sera pris dans l'élément <title> élément.

Les images peuvent également être insérées très facilement dans le corps HTML d'un e-mail. Il suffit de passer le chemin où les images sont physiquement situées comme deuxième paramètre, et Nette les inclura automatiquement dans l'e-mail :

// ajoute automatiquement /path/to/images/background.gif à l'email
$mail->setHtmlBody(
	'<b>Hello</b> <img src="background.gif">',
	'/path/to/images',
);

L'algorithme d'incorporation d'images prend en charge les modèles suivants : <img src=...>, <body background=...>, url(...) à l'intérieur de l'attribut HTML style et la syntaxe spéciale [[...]].

L'envoi d'e-mails peut-il être encore plus facile ?

Les courriels sont comme des cartes postales. N'envoyez jamais de mots de passe ou d'autres informations d'identification par courrier électronique.

Pièces jointes

Vous pouvez, bien entendu, joindre des pièces jointes à un courriel. Utilisez l'adresse addAttachment(string $file, ?string $content = null, ?string $contentType = null).

// insère le fichier /path/to/example.zip dans l'email sous le nom example.zip
$mail->addAttachment('/path/to/example.zip');

// insère le fichier /path/to/example.zip dans l'e-mail sous le nom info.zip
$mail->addAttachment('info.zip', file_get_contents('/path/to/example.zip'));

// joint le contenu du nouveau fichier exemple.txt "Bonjour John !"
$mail->addAttachment('example.txt', 'Hello John!');

Modèles

Si vous envoyez des e-mails en HTML, c'est une excellente idée de les rédiger dans le système de modèles Latte. Comment faire ?

$latte = new Latte\Engine;
$params = [
	'orderId' => 123,
];

$mail = new Nette\Mail\Message;
$mail->setFrom('John <john@example.com>')
	->addTo('jack@example.com')
	->setHtmlBody(
		$latte->renderToString('/path/to/email.latte', $params),
		'/path/to/images',
	);

Fichier email.latte:

<html>
<head>
	<meta charset="utf-8">
	<title>Order Confirmation</title>
	<style>
	body {
		background: url("background.png")
	}
	</style>
</head>
<body>
	<p>Hello,</p>

	<p>Your order number {$orderId} has been accepted.</p>
</body>
</html>

Nette insère automatiquement toutes les images, définit le sujet en fonction de l'élément <title> et génère un texte alternatif pour le corps du HTML.

Utilisation dans l'application Nette

Si vous utilisez des e-mails avec Nette Application, c'est-à-dire des présentateurs, vous voudrez peut-être créer des liens dans les modèles en utilisant l'attribut n:href ou la balise {link}. En principe, Nette Application ne les connaît pas, mais il est très facile de les ajouter. La création de liens peut se faire à l'aide de l'objet Nette\Application\LinkGenerator, que vous obtenez en le passant à l'aide de l'injection de dépendances.

use Nette;

class MailSender
{
	public function __construct(
		private Nette\Application\LinkGenerator $linkGenerator,
		private Nette\Bridges\ApplicationLatte\TemplateFactory $templateFactory,
	) {
	}

	private function createTemplate(): Nette\Application\UI\Template
	{
		$template = $this->templateFactory->createTemplate();
		$template->getLatte()->addProvider('uiControl', $this->linkGenerator);
		return $template;
	}

	public function createEmail(): Nette\Mail\Message
	{
		$template = $this->createTemplate();
		$html = $template->renderToString('/path/to/email.latte', $params);

		$mail = new Nette\Mail\Message;
		$mail->setHtmlBody($html);
		// ...
		return $mail;
	}
}

Dans le modèle, le lien est créé comme dans un modèle normal. Tous les liens créés par LinkGenerator sont absolus :

<a n:href="Presenter:action">Link</a>

Envoi de courriels

Mailer est la classe responsable de l'envoi des e-mails. Elle implémente l'interface Nette\Mail\Mailer et il existe plusieurs mailers prêts à l'emploi que nous allons présenter.

Le framework ajoute automatiquement un service Nette\Mail\Mailer basé sur la configuration au conteneur DI, que vous obtenez en le passant en utilisant l'injection de dépendances.

SendmailMailer

Le mailer par défaut est SendmailMailer qui utilise la fonction PHP mail. Exemple d'utilisation :

$mailer = new Nette\Mail\SendmailMailer;
$mailer->send($mail);

Si vous voulez définir returnPath et que le serveur l'écrase quand même, utilisez $mailer->commandArgs = '-fmy@email.com'.

SmtpMailer

Pour envoyer du courrier via le serveur SMTP, utilisez SmtpMailer.

$mailer = new Nette\Mail\SmtpMailer(
	host: 'smtp.gmail.com',
	username: 'franta@gmail.com',
	password: '*****',
	encryption: 'ssl',
);
$mailer->send($mail);

Les paramètres supplémentaires suivants peuvent être passés au constructeur :

  • port – s'il n'est pas défini, les valeurs par défaut 25 ou 465 pour ssl seront utilisées.
  • timeout – délai d'attente pour la connexion SMTP
  • persistent – utilisation d'une connexion persistante
  • clientHost – désignation du client
  • streamOptions – vous permet de définir les options du contexte SSL pour la connexion.

FallbackMailer

Il n'envoie pas de courrier électronique mais les fait transiter par un ensemble de mailers. Si un mailer échoue, il répète la tentative au suivant. Si le dernier échoue, il recommence à partir du premier.

$mailer = new Nette\Mail\FallbackMailer([
	$smtpMailer,
	$backupSmtpMailer,
	$sendmailMailer,
]);
$mailer->send($mail);

Les autres paramètres du constructeur comprennent le nombre de répétitions et le temps d'attente en millisecondes.

DKIM

DKIM (DomainKeys Identified Mail) est une technologie de messagerie électronique fiable qui permet également de détecter les messages usurpés. Le message envoyé est signé avec la clé privée du domaine de l'expéditeur et cette signature est stockée dans l'en-tête du courriel. Le serveur du destinataire compare cette signature avec la clé publique stockée dans les enregistrements DNS du domaine. En faisant correspondre la signature, il est démontré que l'e-mail provient effectivement du domaine de l'expéditeur et que le message n'a pas été modifié pendant sa transmission.

Vous pouvez configurer le mailer pour qu'il signe les e-mails dans la configuration. Si vous n'utilisez pas l'injection de dépendances, elle est utilisée comme suit :

$signer = new Nette\Mail\DkimSigner(
	domain: 'nette.org',
	selector: 'dkim',
	privateKey: file_get_contents('../dkim/dkim.key'),
	passPhrase: '****',
);

$mailer = new Nette\Mail\SendmailMailer; // ou SmtpMailer
$mailer->setSigner($signer);
$mailer->send($mail);

Configuration de

Aperçu des options de configuration du courrier Nette. Si vous n'utilisez pas l'ensemble du framework, mais seulement cette bibliothèque, lisez comment charger la configuration.

Par défaut, le mailer Nette\Mail\SendmailMailer est utilisé pour envoyer des emails, ce qui n'est pas plus configuré. Cependant, nous pouvons le changer pour Nette\Mail\SmtpMailer:

mail:
	# utilise SmtpMailer
	smtp: true       # (bool) defaults to false

	host: ...        # (string)
	port: ...        # (int)
	username: ...    # (string)
	password: ...    # (string)
	timeout: ...     # (int)
	encryption: ...  # (ssl|tls|null) par défaut null (a un alias 'secure')
	clientHost: ...  # (string) Valeur par défaut: $_SERVER['HTTP_HOST'].
	persistent: ...  # (bool) a pour valeur par défaut false

	# contexte pour la connexion au serveur SMTP, la valeur par défaut est stream_context_get_default()
	context:
		ssl:         # toutes les options sur https://www.php.net/manual/en/context.ssl.php
			allow_self_signed: ...
			...
		http:        # toutes les options sur https://www.php.net/manual/en/context.http.php
			header: ...
			...

Vous pouvez désactiver l'authentification du certificat SSL en utilisant l'option context › ssl › verify_peer: false. Il est strès fortement recommandé de ne pas le faire car cela rendra l'application vulnérable. Au lieu de cela, ajoutez les certificats au magasin de confiance.

Pour augmenter la confiance, nous pouvons signer les courriels en utilisant la technologie DKIM:

mail:
	dkim:
		domain: myweb.com
		selector: lovenette
		privateKey: %appDir%/cert/dkim.priv
		passPhrase: ...

Services DI

Ces services sont ajoutés au conteneur DI :

Nom Type Description
mail.mailer Nette\Mail\Mailer classe d'envoi de courriels
mail.signer Nette\Mail\Signer Signature DKIM
  1. Documentation
  2. Envoi de courriels
version: 4.0