Utilizarea și extinderea API-ului Drupal 8 Mail Partea 1

În această serie de două părți vom explora API-ul de e-mail în Drupal 8. În acest sens vom aborda două aspecte principale: cum să-l folosim programatic pentru trimiterea de e-mailuri și cum să-l extindem pentru utilizarea unui serviciu extern ca Mandrill.

Pentru a demonstra acest lucru, în prima parte vom crea un email personalizat șablon care se utilizează pentru trimiterea de e-mailuri către utilizatorul curent atunci când salvează un nou nod de articole. În plus, vom vedea cum alții pot schimba acest lucru șablon pentru a permite redarea HTML a corpului de e-mail în locul textului standard implicit.

În cea de-a doua parte, vom examina extinderea sistemului de corespondență și integrarea unui API extern pentru livrarea prin e-mail. Pentru aceasta, vom folosi Mandrill și biblioteca PHP care oferă o bază bună pentru interacțiunea cu API-ul său.

Toate lucrările pe care le trecem pot fi găsite în acest depozit Git, ca parte a unui modul Drupal 8 personalizat, pe care îl vom începe să scriem aici. Așa că nu ezitați să verificați dacă doriți să urmați. Să începem.

Prima condiție a acestui modul este cea a acestuia .info fişier:

d8mail.info.yml:

nume: Drupal 8 Descriere Mailer: "Demonstrează utilizarea API-ului Mail în Drupal 8." core: modul 8.x: modul 

Cu acest lucru din drum, putem deja să activa modulul de pe site-ul nostru, dacă vrem.

Cum trimitem un e-mail?

Există doi pași principali necesari pentru a trimite un e-mail programatic cu Drupal 8. Mai întâi trebuie să implementăm hook_mail () pentru a defini unul sau mai multe e-mailuri template-uri. Al doilea pas este să utilizați managerul de e-mail pentru a trimite e-mailuri utilizând unul dintre acestea template-uri.

Deși numit un cârlig, hook_mail () nu este un cârlig tipic, ci mai degrabă o funcție obișnuită, care în general se numește numai de același modul care o implementează. Cu alte cuvinte, atunci când trimiteți un program electronic, trebuie să specificați implementarea numelui modulului hook_mail () si șablon id pe care doriți să îl utilizați și care este definit de acest cârlig. Dar vom vedea asta într-un minut. În primul rând, cum îl implementăm?

d8mail.module:

/ ** * Implementează hook_mail (). * / funcția d8mail_mail ($ key, & $ message, $ params) $ opțiuni = array ('langcode' => $ message ['langcode'];); comanda (cheia $) caz 'node_insert': $ message ['din'] = \ Drupal :: config ('system.site') -> get ('mail'); $ message ['subject'] = t ('Nod creat: @title', array ('@ title' => $ params ['node_title']), $ opțiuni); $ message ['body'] [] = SafeMarkup :: checkPlain ($ params ['mesaj']); pauză;  

Aceasta este o implementare foarte simplă care definește una șablon identificată ca node_insert (The cheie $). Celelalte două argumente privind funcțiile sunt:

• $ mesaj: trecut prin referință și în interiorul căruia adăugăm cât mai multe informații despre e-mailul nostru de care avem nevoie 
• $ params: o serie de date suplimentare care trebuie să intre în e-mail și care sunt transmise de managerul de e-mail atunci când încercăm să trimitem e-mailul

După cum puteți vedea, construim $ mesaj array cu valorile pe care dorim ca acest e-mail să fie inclus în toate apelurile. Setăm o valoare prestabilită din valoare care este preluată din sistemul de configurare și care reprezintă adresa principală de e-mail a site-ului. Am stabilit un e-mail cu numele de bază subiect care permite destinatarului să știe că a fost creat un nou nod, urmat de numele nodului (care va fi transmis prin $ params array). Subiectul este, de asemenea, translatabil în limba care este transmisă de la apelant. 

În sfârșit, conducem mesajul corp prin ștanțelul de șir, deoarece textul poate conține HTML și ar putea să fie trunchiat dacă nu codificăm elementele HTML. Și din moment ce folosim SafeMarkup clasa, trebuie să utilizare la început:

utilizați Drupal \ Component \ Utility \ SafeMarkup; 

În plus, corpul mesajului este o matrice care va fi ulterior implozie într-un șir. Și, evident, există alți parametri pe care îi putem stabili, cum ar fi anteturile, dar acest lucru va fi suficient pentru acest exemplu.

Și asta e tot pentru hook_mail () punerea în aplicare. Acum, hai să ne întoarcem la codul care se execută de fiecare dată când este creat un nou nod, hook_entity_insert ():

/ ** * Implementează hook_entity_insert (). * / funcția d8mail_entity_insert (Drupal \ Core \ Entity \ EntityInterface $ entitate) if ($ entită-> getEntityTypeId ()! == 'nodul' || ($ entity-> getEntityTypeId () === nodul && $ entitate -> bundle ()! == 'articolul')) retur;  $ mailManager = \ Drupal :: serviciu ('plugin.manager.mail'); $ modul = 'd8mail'; $ cheie = 'node_insert'; $ to = \ Drupal :: curentUser () -> getEmail (); $ params ['mesaj'] = $ entitate-> get ('body') -> valoare; $ params ['node_title'] = $ entitate-> etichetă (); $ langcode = \ Drupal :: curentUser () -> getPreferredLangcode (); $ send = true; $ result = $ mailManager-> mail ($ modul, $ cheie, $ la, $ langcode, $ params, NULL, $ send); if ($ result ['result']! == true) $ message = t ('A apărut o problemă la trimiterea notificării prin e-mail către @email pentru crearea nodului @id. , '@id' => $ entitate-> id ())); drupal_set_message ($ mesaj, 'eroare'); \ Drupal :: logger ( 'd8mail') -> eroare ($ mesaj); întoarcere;  $ message = t ('A fost trimisă o notificare prin e-mail către @email pentru crearea nodului @id.', array ('@ email' => $ to,'id ' ; drupal_set_message ($ mesaj); \ Drupal :: logger ( 'd8mail') -> Notă ($ mesaj);  

Acest cârlig se declanșează după fiecare salvare a nodului și tot ce trebuie să facem este să ne asigurăm că țintim nodul corect și să includem logica noastră.

După verificarea faptului că entitatea nodului este de tip articol, vom încărca serviciul de e-mail Drupal și vom începe să setăm câteva valori pentru e-mail. Avem nevoie de următoarele informații:

• numele modulului care se implementează hook_mail () și ne definește șablon (ceea ce am menționat mai sus)
• șablon id ( cheie $)
• adresa de e-mail a destinatarului (cea găsită în contul curent de utilizator)
• limba ($ langcode) care intră în interiorul $ params și care vor fi utilizate pentru a traduce mesajul subiectului
• titlul nodului care va fi adăugat la subiectul e-mailului
• corpul de e-mail, care în cazul nostru va fi valoarea câmpului corpului nodului
• valoarea booleană indicând dacă e-mailul trebuie trimis efectiv

Apoi, trecem toate aceste valori la Poștă() metoda managerului de mail. Acesta din urmă este responsabil pentru construirea e-mailului (sunând la dreapta hook_mail () punerea în aplicare fiind un aspect al acesteia) și, în final, delegarea livrării efective către plugin-ul responsabil. Implicit, acesta va fi PHPMail, care utilizează implicit Poștă() funcția care vine cu PHP.

Dacă managerul de mail reușește să trimită e - mailul (livrarea reală nu este luată în considerare, ci mai degrabă o acțiune PHP de succes), Poștă() metoda va returna o matrice care conține a rezultat cheie cu ceea ce returnează pluginul de e-mail. Dacă verificăm valoarea respectivă, putem afla dacă acțiunea de e-mail a avut succes și a informat utilizatorul că le-am notificat despre acțiunea lor. În caz contrar, vom imprima și vom înregistra un mesaj de eroare.

Și asta e vorba de asta. Ștergerea cache-ului și crearea unui nod de articole ar trebui să aterizeze un e-mail în căsuța de e-mail. Dacă nu primiți nimic și nu există semne de eroare pe ecran, asigurați-vă că verificați jurnalele de server și coada de e-mail pentru a verifica dacă e-mailurile sunt trimise.

Înainte de a continua, aș dori să fac o notă rapidă cu privire la această implementare a cârligului. În acest exemplu, am plasat toată logica în ea direct. În plus, am folosit o întoarcere timpurie în partea de sus, ceea ce în esență înseamnă că nici o altă logică nu poate fi adăugată decât cea specifică nodurilor articol. În aplicațiile reale, recomand să refacționați logica de trimitere într-o funcție separată sau într-o clasă separată și să amânați aceasta. În plus, nu trebuie să utilizați întoarcerea timpurie în interiorul implementărilor cârligului, ci să apelați alte funcții dacă condițiile sunt îndeplinite. 

Cum schimbăm un e-mail?

Odată ce toate acestea sunt în vigoare, avem la dispoziție un alt instrument care ne permite să modificăm o astfel de configurație existentă: hook_mail_alter (). Acest cârlig este chemat din cadrul managerului de e-mail înainte ca plugin-ul de mail responsabil să trimită e-mailul. Scopul este de a permite altor module să efectueze modificări finale la un e-mail existent care este trimis.

Deși acest lucru poate fi utilizat și de alte module, vom ilustra un exemplu de implementare din cadrul aceluiași modul cu care lucrăm. În acest scop, vom modifica e-mailul schimbând una dintre anteturile sale implicite pentru a le transforma din text simplu în HTML. Iată cum putem face acest lucru:

/ ** * Implementează hook_mail_alter (). * / funcția d8mail_mail_alter (& $ message) comutare ($ message ['key']) caz 'node_insert': $ message ['headers'] ['Content-Type'] = 'text / html; charset = UTF-8; format = curs; delsp = da; pauză;  

După cum puteți vedea, aceasta este o simplă modificare a Tipul de conținut header care transformă e-mailul în HTML. În acest fel, entitățile HTML text simple vor fi analizate ca HTML de către clienții de mail. Și folosind casetele de comutare, ne asigurăm că acest lucru se întâmplă numai pentru e-mail șablon am definit mai devreme.

Un lucru de observat aici este că alter cârligul este chemat după ce este relevant hook_mail () punerea în aplicare. După aceasta, singura prelucrare care se întâmplă pe e-mail se face în interiorul format() metoda pluginului de mail (impusă de interfața sa).

Concluzie

Și că este destul de mult tot nu există pentru a trimite e-mailuri programatic folosind Drupal 8. Am văzut pașii necesari pentru a seta programatic e-mail template-uri care sunt hidratate de managerul de mail ori de câte ori o dorim. Am menționat, de asemenea, pluginul implicit de livrare a poștei care este folosit pentru a trimite e-mailuri în Drupal 8. Și, în sfârșit, am văzut cum alte module pot modifica acum e-mailurile noastre prin adăugarea de antete noi, schimbarea subiectului, concatenarea valorilor în corpul poștal , etc.

În următorul articol vom examina înlocuirea pluginului PHPMail implicit cu implementarea noastră personalizată. Vom configura un e-mail care utilizează Mandrill cu ajutorul bibliotecii sale PHP. Scopul este să permitem modulului nostru să folosească acest mailer, în timp ce restul aplicației continuă să utilizeze implicit PHPMailer.