Modèle d’e-mail Dev
Utilisation
Définition des contextes
Dans vos bundles locaux, vous devez créer un fichier de configuration définissant les contextes de messagerie.
L’emplacement est : *Bundle/Resources/config/email-contexts.yml
Le fichier doit contenir la clé email-contexts en tant que root.
Chaque contexte aura le nom de sa clé dans le contexte.
Un contexte peut être défini à l’aide des clés suivantes :
subject : Objet par défaut de l’e-mail.
fromAddress : Adresse d’envoi par défaut.
textBody : Contenu par défaut en texte brut.
htmlBody : Contenu HTML par défaut.
data {exclamation-triangle icon} required : Liste des données dans le contexte.
Les données d’un contexte (données clés) sont définies à l’aide des clés suivantes :
tokenEntities : tableau associatif des jetons de remplacement disponibles dans le corps de l’e-mail, nom de variable => type
loopEntities : liste des structures de boucle disponibles (voir l’opération Modèle de devis pour plus d’informations)
Données contextuelles
Les données de chaque contexte sont définies dans un tableau associatif permettant d’exposer les propriétés (ou méthodes) des objets ayant l’annotation @Reportable (ValueInCommonBundleAnnotationReportable).
Par exemple, nous devons afficher le nom d’utilisateur de l’utilisateur actuel dans l’e-mail : nous définirons la clé tokenEntities de cette manière :
email-contexts: product-added-to-cart: data: tokenEntities: user: AppBundle\Entity\User
À partir de l’annotation @Reportable, l’éditeur visuel affichera une liste de complétion automatique répertoriant les éléments visibles de l’objet en question :
Vous n’avez peut-être pas la possibilité d’ajouter ces annotations sur les entités (ou tout autre type d’objet) du générique.
Dans ce cas, il vous suffit de configurer un décorateur pour l’objet et d’appliquer l’annotation @Reportable aux getters de ce décorateur.
Exemple : l’entité AppBundleEntityProduct ne comporte aucune annotation @Reportable. Nous créons le décorateur suivant :
use ValueIn\CommonBundle\Annotation\Reportable;class ProductInformation{ /** * @var Product */ private $product; public function __construct( Product $product ) { $this->product = $product; } /** * @Reportable("Title") * * @return string */ public function getTitle(): string { return $this->product->getTitle(); }}
Lorsque nous appelons le service de messagerie électronique, nous transmettons ce décorateur en tant que paramètre afin que les types des tokenEntities soient valides (voir l’exemple d’utilisation).
Exemple de contexte
email-contexts: product-added-to-cart: subject: Your added a product to your cart fromAddress: no-reply@your-shop.com textBody: | Hello [[user.username]], You added product [[product.title]] into your cart. Here some detailed informations about this product : {% for attr in product.attributes %} - {{ attr.name }}: {{ attr.value }} {% endfor %} htmlBody: | <p>Hello [[user.username]],</p> <p>You added product <b>[[product.title]]</b> into your cart.</p> <p>Here some detailed informations about this product :</p> <ul> <li class="productAttribute"> <b>[[productAttribute.name]] : </b> [[productAttribute.value]] </li> </ul> data: tokenEntities: user: AppBundle\Entity\User product: Local\EmailBundle\Model\Template\Email\ProductInformation productAttribute: Local\EmailBundle\Model\Template\Email\ProductAttributeInformation loopEntities: - key: productAttribute from: product.attributes label: Product Attribute types: - li color: hsl(195, 53%, 79%)
Priorité de chargement
Les contextes sont chargés dans cet ordre de priorité :
contextes génériques
contextes de paquets locaux, par ordre alphabétique croissant du nom du paquet (TestBundle sera chargé avant ZooBundle)
REMARQUE : Le bundle local doit implémenter l’interface AppBundleInterfacesSwitchable et la méthode isEnabled doit renvoyer la valeur true pour que la configuration soit prise en compte.
Surcharge et fusion de contextes
Les contextes sont définis dans l’application générique.
Il est possible de surcharger ces contextes en les redéfinissant dans vos bundles locaux.
La surcharge est effectuée à l’aide de la fonction array_replace_recursive.
Vous pouvez également surcharger les contextes définis dans les bundles locaux, à condition que la surcharge soit effectuée dans le bon ordre de priorité. (ABundle ne pourra pas remplacer les contextes de BBundle, mais l’inverse sera possible).
Débogueur
À partir du logger symfony, il est possible de vérifier le chargement des contextes. L’ordre de chargement est chronologique et la fusion finale s’affiche en dernier.
Utilisation du service de messagerie électronique
AppBundleServiceEmailSender permet d’envoyer un e-mail pour un contexte donné.
La méthode à appeler est sendEmailFromTemplate(string $templateName, string $to, ?string $toName, array $params = []): void
$templateName est le nom du contexte que vous avez défini, $to est l’adresse e-mail de destination. Le paramètre facultatif $toName vous permet d’attribuer un nom à l’adresse e-mail et le tableau $params est le tableau de variables qui seront utilisées dans le rendu du corps de l’e-mail.
Exemple
$this->emailSender->sendEmailFromTemplate('product-added-to-cart', $user->getEmail(), $user->getUsername(), [ 'user' => $user, 'product' => new ProductInformation($event->getProduct()), 'productAttribute' => new ProductAttributeInformation,]);