MailTool

La classe MailTool est le moteur d'envoi d'emails de Magepattern 3. Elle remplace l'ancienne implémentation SwiftMailer par Symfony Mailer. Ce composant a été conçu pour être totalement flexible : il accepte les configurations modernes par DSN (Data Source Name) tout en restant compatible avec vos anciens tableaux de paramètres SMTP.

Namespace : Magepattern\Component\Tool\MailTool

Logique de Transport

L'outil initialise le moteur d'envoi selon deux formats d'entrée :

1. Format DSN (Recommandé) : Une chaîne unique contenant protocole, identifiants, hôte et port (ex: smtp://user:pass@host:port).
2. Format Legacy (Tableau) : Un tableau associatif de clés setHost, setPort, setUsername, etc., converti automatiquement en DSN par la classe.

Exemples d'utilisation

1. Initialisation du transport Vous choisissez votre mode d'instanciation selon la source de vos réglages.

A. Utilisation directe via DSN (Local/Mailhog)

use Magepattern\Component\Tool\MailTool;

$mailTool = new MailTool('smtp://localhost:1025');

B. Utilisation via un tableau d'options (Legacy)

$options = [
    "setHost"       => "smtp.example.com",
    "setPort"       => 587,
    "setUsername"   => "mon-user",
    "setPassword"   => "mon-pass",
    "setEncryption" => "tls"
];

$mailTool = new MailTool('smtp', $options);

2. Création et Envoi de mails La création du message est séparée de l'ajout de pièces jointes pour plus de modularité.

A. Envoi simple (Sans pièce jointe)

// 1. Préparation du message
$email = $mailTool->createMessage(
    "Sujet du mail",              // Subject
    "admin@site.com",             // From
    "contact@site.com",           // Reply-To
    ["user@mail.com" => "Jean"],  // Recipients [email => Nom]
    "<h1>Bienvenue !</h1>"        // Body (HTML)
);

// 2. Envoi
$mailTool->send($email);

B. Envoi avec pièces jointes (Optionnel) La méthode attachFiles accepte des chemins de fichiers simples ou des tableaux pour renommer les fichiers.

$email = $mailTool->createMessage("Votre facture", "compta@site.com", "compta@site.com", $dest, "...");

// Ajout de fichiers
$mailTool->attachFiles($email, [
    '/data/pdf/facture_01.pdf',           // Chemin direct
    [
        'path' => '/data/tmp/image.jpg',
        'name' => 'photo-profil.jpg'      // Nom affiché dans le mail
    ]
]);

$mailTool->send($email);

Liste des méthodes

Méthode	Paramètres	Description
__construct()	string $dsn, array $options	Initialise le transport (SMTP, SMTPS ou Sendmail).
createMessage()	$sub, $from, $reply, $to, $body, $receipt	Construit l'objet Email (inclut le nettoyage texte brut).
attachFiles()	Email $email, array $files	Ajoute une liste de fichiers au message spécifié.
send()	Email $email	Exécute l'envoi et log les erreurs en cas d'échec.

Notes Techniques

Nettoyage Automatique : La classe génère automatiquement une version text/plain de votre corps HTML via FormTool::tagClean() pour optimiser la délivrabilité (anti-spam).

Accusé de réception : Vous pouvez activer un accusé de réception en passant une adresse email en 6ème paramètre de createMessage().

Logging : Toute erreur d'envoi (serveur injoignable, timeout) est capturée et enregistrée dans le Logger de Magepattern avec le niveau d'erreur approprié.

MAMP / Local : Pour Mailhog, utilisez toujours smtp://localhost:1025.

Intégration Smarty (Templates)

Le MailTool communique nativement avec le SmartyTool pour générer des emails dynamiques. Cette liaison permet d'utiliser toute la puissance des templates (variables, boucles, plugins personnalisés) pour le corps de vos messages.

1. Méthode Automatisée (sendTemplate) C'est la méthode recommandée pour la majorité des cas. Elle automatise le rendu du template et l'envoi en une seule ligne. Elle supporte désormais l'envoi de pièces jointes via un paramètre optionnel.

Exemple : Envoi d'une facture

$mailer = new MailTool('smtp://localhost:1025');

$mailer->sendTemplate(
    'frontend',                  // Contexte Smarty
    'emails/order_success.tpl',  // Fichier template
    ['order_ref' => '2026-001'], // Données Smarty
    "Votre confirmation",        // Sujet
    "shop@site.be",              // Expéditeur
    ["client@test.be" => "A."],  // Destinataire(s)
    ['/path/to/invoice.pdf']     // [Optionnel] Pièces jointes
);

2. Méthode Manuelle (Contrôle total) À utiliser si vous avez besoin de manipuler l'objet Email de Symfony (en-têtes spécifiques, logique conditionnelle complexe avant envoi) ou si vous utilisez MJML pour compiler votre rendu en amont.

// 1. Récupération du rendu HTML
$smarty = SmartyTool::getInstance('frontend');
$htmlBody = $smarty->assign(['key' => 'value'])->fetch('emails/custom.tpl');

// 2. Préparation du mailer
$mailer = new MailTool('smtp://localhost:1025');

// 3. Création manuelle du message
$email = $mailer->createMessage(
    "Sujet spécifique",
    "info@site.be",
    "info@site.be",
    ["dest@test.be" => "Nom"],
    $htmlBody
);

// 4. Actions supplémentaires avant envoi
$email->getHeaders()->addTextHeader('X-Custom-Header', 'Magepattern3');

// 5. Envoi
$mailer->send($email);

Signature de la méthode sendTemplate

Argument	Type	Description
$context	string	Nom du contexte enregistré dans SmartyTool (ex: 'admin').
$template	string	Chemin relatif du fichier .tpl depuis le template_dir.
$data	array	Tableau associatif des variables à assigner au template.
$subject	string	Objet de l'email.
$from	string	Adresse email de l'expéditeur.
$to	array	Tableau des destinataires : ['email' => 'Nom'].
$files	array	[Optionnel] Liste de chemins vers des fichiers locaux.

Notes de fonctionnement

Version Texte brute : sendTemplate appelle createMessage en interne, ce qui garantit que vos templates HTML sont automatiquement convertis en version texte simplifié (via FormTool::tagClean) pour améliorer l'envoi.

Gestion des erreurs : Si le rendu Smarty échoue (template introuvable) ou si une pièce jointe est inaccessible, l'erreur sera capturée, loguée via Logger, et la méthode retournera false.