Débbuger les mails sous Drupal 9 avec Mailcatcher

Travailler sur la partie mail d'un site web a toujours été une tâche repoussante pour moi. Gérer l'attachement des fichiers liés, faire le templating avec du inline css ?, "s'amuser" avec des <table> dans certains cas, gérer les exceptions de ce merveilleux Office365... Pas grand chose de fun à ce mettre sous la dent.

Ce qui est le plus frustrant c'est de s’apercevoir que le site en local est branché à un serveur SMTP fonctionnel. Ce qui veux dire que tous les mails partent vraiment vers les adresses mails des utilisateurs.

Quand il s'agit d'un mail vers une adresse de test ce n'est pas trop gênant, mais lorsque l'on se rend compte d'avoir lancer un script ou d'avoir paramétré un CRON en local et qu'il envoi des dizaines voir centaines de mails aux vrais clients, là on commence à sentir la petite goutte de sueur qui coule le long de la tempe.

Pour bien achever le moral, c'est seulement dans un second temps que l'on pense aux liens vers le site en local que contiennent tous ces mails.
À ce moment précis on entrouvre la possibilité de se reconvertir dans l'élevage des bichons frisés dans le Gers.

Après ces quelques péripéties, j'ai décidé de rechercher une méthode afin que tous les mails soient redirigés vers ma propre adresse mail. Ceci à bien fonctionné dans un premier temps mais lorsque j'avais des fonctionnalités de routage depuis un formulaire, j'ai du commencer à bricoler pour savoir à qui le mail été réellement destiné. Je mettais la vraie adresse mail à la fin du sujet ou dans le corps du mail... Bref c'était devenu du bricolage, il fallait une autre solution.
Quitte à en trouver une nouvelle autant avoir tout en local afin de pouvoir travailler même sans connexion internet.

Je me suis donc mis à la recherche d'une solution pour avoir un serveur SMTP en local ainsi qu'une petite interface web afin de consulter les mails.

C'est là que j'ai trouvé et utilisé Mailcatcher.

1) Description de Mailcatcher

En vulgarisant, Mailcatcher est un outil s'exécutant en ligne de commande et qui lance un serveur SMTP sur la machine. Il utilise le port 1025 et comme adresse IP 127.0.0.1 puisque qu'il est en local. Du côté applicatif rien ne change, vous configurez vos envois de mail en précisant l'IP et le port cités ci-dessus.

Là où c'est intéressant c'est que le cheminement des mails s'arrêtent à ce moment précis, Mailcatcher reçoit les requêtes pour distribuer les mails mais comme il est en local il n'est pas fait pour continuer le processus d'envoi de mail via le réseau. Mailcatcher possède également une petite interface web qui permet de visionner les mails (en version texte comme HTML) et ainsi on peut tester et débugger le contenu des mails que le site envoie.

L'interface web est consultable à l'adresse http://127.0.0.1:1080/ une fois l'outil lancé. Cela permet de vérifier les adresses de départ et d'arrivé, le sujet, corps du mail...

Voici la documentation officielle pour une installation simple et efficace de cet outil.

2) Utiliser Mailcatcher avec Drupal

Plusieurs solutions sont disponibles afin d'utiliser Mailtcatcher. Si le site utilise la fonction d'envoi de mail PHP, on peut ajouter la ligne ci-dessous dans le fichier php.ini d'Apache.

php_admin_value sendmail_path "/usr/bin/env catchmail -f some@from.address"

Personnellement je n'utilise pas cette solution car cela m'oblige à le faire sur chaque version de PHP que je possède. En mettant à jour mes sites vers les versions PHP plus récentes, c'est sûr à 100% que j'oublierai cette partie.
Sur tous mes projets Drupal, j'installe le module SMTP Authentication Support disponible sur les versions 8 et 9 du CMS.
Une fois installé, le module dispose d'une page d'administration (/admin/config/system/smtp) afin de renseigner les informations du serveur SMTP à utiliser pour l'envoi des mails.

Sur cette page je recommande de renseigner les informations du serveur SMTP qui est utilisé en production. Comme c'est de la configuration elle sera exportée et versionnée.

Pour supplanter ces configurations sur un environnement autre que la production et ne pas retomber dans le genre de soucis décrits en préambule de cet article, il faut surcharger les configurations du module SMTP dans le fichier /sites/default/settings.local.php comme ceci :

$config['smtp.settings']['smtp_host'] = '127.0.0.1';
$config['smtp.settings']['smtp_port'] = '1025';
$config['smtp.settings']['smtp_protocol'] = 'standard';
$config['smtp.settings']['smtp_username'] = '';
$config['smtp.settings']['smtp_password'] = '';

3) Tester le fonctionnement

Pour tester que tout soit correct, il est possible de renseigner une adresse mail de test dans le champ "L'adresse e-mail où le message de test sera envoyé" de la page de configuration SMTP. En validant le formulaire le module va envoyer un mail.
En se rendant sur http://127.0.0.1:1080/ on peut voir le mail dans l'interface web de Mailcatcher.

Il est maintenant possible de tester les fonctionnalités Drupal envoyant des mails en conditions réelles, mettre du debug dans le corps des mails... sans qu'ils sortent du local.
Toutes ces parties sont maintenant isolées du réseau internet et on peut travailler en toute sérénité.

N'hésitez pas à me dire si vous utilisez une autre solution lors du développement des fonctionnalités liées aux mails ou si vous avez atteint des limites à l'utilisation de Mailcatcher.