L’API TYPO3 regroupe un nombre impressionnant de fonctionnalités dont certaines ne sont pas très connues.
Après avoir passé en revue les variables sessions puis la gestion des liens typolink, voici maintenant comment envoyer des emails dans ses développements avec le CMS TYPO3.
Cette partie de l’API a été publiée avec la sortie de TYPO3 v4.5 et à fait l’objet d’un article dédié sur buzz.typo3.org.
A) Utilité de cette fonctionnalité
Pourquoi utiliser cette fonction? pourquoi ne pas utiliser directement la fonction « mail » de PHP? PARCE QUE!!!!!
En premier lieu, cette fonction est beaucoup plus facile à utiliser que la fonction « mail » de PHP. Il est assez complexe de gérer les pièces attachées ainsi que les différentes parties de l’email avec la fonction « mail() » de base et les risques d’avoir un mail illisible ou mal formaté sont importants.
De plus, la configuration de l’API mail de TYPO3 est regroupée dans l’install tool, ce qui veut dire qu’un changement de configuration sur son hébergement ne nécessite pas de retouche du code PHP, mais simplement d’adapter la configuration générale via l’install tool.
B) Fonctionnement de base
En se basant sur l’article dédié sur buzz.typo3.org, on peut préparer le code minimum pour l’envoi d’un email.
<?php
//on prepare les variables
$emailEmetteur='..@...fr';
$nomEmetteur='...';
$emailDestinataire='..@...com';
$nomDestinataire='...';
$sujet='...';
$contenuHTML='contenu <i>email</i> au format <b>HTML<b>';
//on declare l'objet mail
$email= t3lib_div::makeInstance('t3lib_mail_Message');
//on parametre l'emetteur
$email->setFrom(array($emailEmetteur => $nomEmetteur));
//on parametre le destinataire
$email->setTo(array($emailDestinataire => $nomDestinataire));
//on parametre le sujet de l'email
$email->setSubject($sujet);
//on ajoute le contenu sans preciser si c'est du texte ou de l'HTML
$email->setBody($contenuHTML);
//on envoie l'email
$email->send();
?>
Et HOP, il est parti. Simple, non?
C) format de l’email (HTML ou texte brut)
Si on ne précise pas le format du contenu (HTML ou texte brut), le composant email décide à notre place en fonction de la présence ou l’absence de code HTML. Dans cette situation, l’affichage sur un lecteur compatible uniquement « texte brut » n’est pas garanti si le texte envoyé contient du code HTML.
Pour conserver la compatibilité, nous allons forcer la partie HTML et ajouter la prise en compte de l’alternative textuelle. Pour cela on va modifier la dernière partie du script :
<?php //on ajoute le contenu en precisant la version HTML $email->setBody($contenuHTML, 'text/html'); //on ajoute le contenu pour la version texte $email->addPart(strip_tags($contenuHTML), 'text/plain'); //on envoie l'email $email->send(); ?>
L’email est maintenant compatible HTML et Texte brut.
D) Gestion des destinataires
Après avoir configuré le contenu, nous allons personnaliser les destinataires.
Il existe plusieurs types de destinataires :
– les destinataires « officiels » (fonctions setTo et addTo)
– les destinataires en « copie » (fonctions setCc et addCc)
– les destinataires en « copie cachée » (fonctions setBcc et addBcc)
Pour chaque type de destinataires, il existe 2 fonctions permettant d’effectuer le paramétrage pour l’email : une fonction « set… » et « add… ».
La fonction « set… » permet de définir complètement le destinataire en supprimant le paramétrage précédent s’il existe.
La fonction « add… » permet d’ajouter un nouveau destinataire sans supprimer les destinataires déjà paramétrés.
Pour la suite, nous n’allons utiliser que les fonctions « set… » pour que cela soit plus simple à comprendre.
On peut préciser des destinataires en copie (visible) :
<?php //on prepare les infos du destinataire en copie $emailDestinataireCopie='..@...net'; $nomDestinataireCopie='...'; [...] //on ajoute le destinataire en copie $email->setCc(array($emailDestinataireCopie => $nomDestinataireCopie)); //on envoie l'email $email->send(); ?>
Ainsi que des destinataires en copie cachée (non visible) :
<?php //on prepare les infos du destinataire en copie $emailDestinataireCopieCachee='..@...org'; $nomDestinataireCopieCachee='...'; [...] //on ajoute le destinataire en copie $email->setBcc(array($emailDestinataireCopieCachee => $nomDestinataireCopieCachee)); //on envoie l'email $email->send(); ?>
E) Ajout de pièces jointes
Il peut être utile de joindre une pièce jointe à un email, comme le Powerpoint de ses dernières vacances sur la côte d’azur, ou encore une vidéo avec plein de petits lolcats trop mignons:
<?php
//on ajoute la piece jointe
$email->attach(Swift_Attachment::fromPath('fileadmin/mes_super_vacances_en_maillot_de_bain.ppt'));
//on envoie l'email
$email->send();
?>
Il est aussi possible de donner un nom précis à la pièce jointe. Cela peut être utile lorsque l’on ne désire pas montrer le nom d’origine du fichier.
<?php
//on ajoute la piece jointe
$email->attach(Swift_Attachment::fromPath('fileadmin/chat_de_la_voisine.avi')->setFilename('chat_trop_mignon.avi'));
//on envoie l'email
$email->send();
?>
F) l’inclusion d’image dans le corps de l’email
Pouvoir envoyer une pièce jointe, c’est bien…. mais ajouter une image directement dans le corps du mail c’est bien aussi.
Cela permet par exemple d’ajouter une image dans une signature en bas d’email, ou un logo en haut d’email.
On ne peut pas utiliser la fonction « attach() » car cela mettrait simplement la photo en pièce jointe, on va donc utiliser la fonction »embed() » qui permet d’inclure un élément dans le corps du message.
Nous allons inclure l’image « fileadmin/images/signature‑anime.gif »
<?php
//le contenu de l'email pour inserer une image
$contenuHTML='contenu email au format texte ou <b>HTML<b>.<br/> Signature : <img src="';
//on appelle la fonction embed() qui va generer le chemin vers l'image
$contenuHTML.= $email->embed(Swift_Image::fromPath('fileadmin/images/signature‑anime.gif')) ;
//on fini le reste de la balise img et du mail
$contenuHTML.='" title="smiley signature anime" alt="smiley signature anime"/>';
//on ajoute le contenu en precisant la version HTML
$email->setBody($contenuHTML, 'text/html');
//on ajoute le contenu pour la version texte
$email->addPart(strip_tags($contenuHTML), 'text/plain');
//on envoie l'email
$email->send();
?>
Nous avons fait manuellement le remplacement, mais cela peut vite devenir fastidieux de faire tous ces remplacements à la main…
Et puis pourquoi se fatiguer à le faire nous même quand le code peut le faire à notre place.
Allons y pour un petit coup d’expression régulière :
<?php
//le contenu de l'email pour inserer une image
$contenuHTML='contenu email au format texte ou <b>HTML<b> avec une image <img src="fileadmin/images/gif-anime-chat-3.gif" title="gif anime chat" alt="gif anime chat"/>.<br/>';
// on ajoute une signature avec une image
$contenuHTML.=' Signature : <img src="fileadmin/images/papillonviolet-2.gif" title="signature email animé" alt="signature email animé"/>';
//on va recherche toutes les balises images
preg_match_all('/<img [^>]*src=["|']([^"|']+)[^>]*>/i', $contenuHTML, $images);
//si on a des resultats
if (is_array($images[0])){
//on supprime les doublons
$images[0]=array_unique($images[0]);
//on prepare les tableaux des correspondances
$remplacement=array();
$remplacement=array();
//pour chaque image detectee
foreach ($images[0] as $key=>$value) {
//on genere l'url interne a partir de l'image d'origine
$cid = $email->embed(Swift_Image::fromPath($images[1][$key]));
//on remplit les tableaux des correspondances
$remplacement_from[$cid]=$value;
$remplacement_to[$cid]=str_replace($images[1][$key], $cid, $value);
}
//on effectue le remplacement des images par leur url interne dans le texte de l'email
$contenuHTML=str_replace($remplacement_from, $remplacement_to, $contenuHTML);
}
//on ajoute le contenu en precisant la version HTML
$email->setBody($contenuHTML, 'text/html');
//on ajoute le contenu pour la version texte
$email->addPart(strip_tags($contenuHTML), 'text/plain');
//on envoie l'email
$email->send();
?>
Et voila…. Maintenant il n’y a plus d’excuse pour ne pas envoyer un petit e-mail, depuis son site TYPO3, pour souhaiter un joyeux anniversaire ou une bonne année….
G) Références
– Buzz.typo3.org: New mail API for the core
– Documentation SwiftMailer