Cum să trimiți e-mailuri cu PHP utilizând Twilio SendGrid și Mezzio

Publicat: 2021-03-24

E-mailul este un instrument de comunicare la fel de important ca întotdeauna. Pentru a vă ajuta să utilizați mai bine e-mailul, vă voi arăta cum să trimiteți e-mail folosind cadrul PHP Mezzio și API-ul Twilio SendGrid.

Mai exact, veți învăța cum să trimiteți e-mailuri atât cu text simplu, cât și cu corpuri HTML, iar asta include un atașament PDF. De asemenea, veți învăța cum să utilizați funcționalitatea de șabloane tranzacționale de la Twilio SendGrid pentru a simplifica crearea de corpuri de e-mail atât de către echipa de dezvoltare, cât și de către orice altă echipă din organizația dvs.

Sună bine? Sa incepem.

Prezentare generală rapidă a aplicației

Ca o modalitate de a face acest tutorial mai semnificativ, pretindeți că codul pe care îl vom scrie face parte dintr-un magazin de comerț electronic online fictiv, construit cu Mezzio, numit The Little PHP Shop - în special, partea imediat după ce un client face o achiziție. În acel moment al fluxului de utilizatori, clientul primește un e-mail prin care îi mulțumește pentru achiziție și include o factură PDF pentru înregistrările lor.

Vom crea o clasă Handler pentru a trimite e-mailul post-cumpărare, care va primi detaliile de cumpărare dintr-o comandă finalizată de client. Cu aceste informații de achiziție, clasa Handler va folosi apoi mai multe clase din API-ul PHP SendGrid pentru a construi și a trimite e-mailul de confirmare a achiziției.

Dintre acestea, cele mai importante sunt „SendGrid\Mail\Mail” și „\SendGrid”. „SendGrid\Mail\Mail” este obiectul care stochează toate proprietățile unui mesaj de e-mail pe care îl vom trimite prin Twilio SendGrid. Obiectul „SendGrid” formează stratul de transport, facilitând trimiterea de e-mailuri prin Twilio SendGrid.

Cerințe preliminare

Pentru a finaliza acest tutorial, veți avea nevoie de următoarele 4 lucruri în mediul dvs. de dezvoltare locală:

  1. cont Twilio SendGrid
  2. PHP 7.4 cu extensiile cURL , mbstring și O pen SSL instalate și activate
  3. Composer instalat la nivel global
  4. răsuci

Folosește aplicația Mezzio

Mai întâi trebuie să creăm aplicația de bază. Pentru a face asta, vom folosi, ca întotdeauna, Scheletul Mezzio pentru a o face pentru noi. Odată ce schelem aplicația de bază, vom trece la directorul de proiect nou creat. Apoi rulați următoarele comenzi în terminal, urmând solicitările pentru prima:

Instalați dependențele necesare

Cu proiectul schelă, trebuie să adăugăm 3 dependențe suplimentare pentru a finaliza proiectul. Acestea sunt:

  • Biblioteca PHP API a Twilio SendGrid pentru interacțiunea cu API-ul Twilio SendGrid
  • Client HTTP PHP pentru trimiterea cererilor HTTP
  • PHP Dotenv pentru stocarea și preluarea variabilelor de mediu

Pentru a le instala, executați următoarea comandă în terminalul dvs.:

Inițializați PHP Dotenv

Cu dependențele instalate, încărcăm PHP Dotenv astfel încât acesta să citească variabilele setate în „.env” și să le facă disponibile pentru PHP ca variabile de mediu. Pentru a face asta, introduceți următorul cod în „public/index.php”, imediat după „require vendor/autoload.php”.

Adăugați detaliile contului Twilio SendGrid

Acum trebuie să furnizați aplicației cheia dvs. API SendGrid. Pentru a face acest lucru, după ce vă conectați la Twilio SendGrid , navigați la „Setări -> Chei API . " Odata acolo:

  1. Faceți clic pe „ Creare cheie API ” pentru a crea o cheie API
  2. Dați un nume noii chei API, acceptați permisiunea implicită a cheii API „ Acces complet ” și faceți clic pe „ Creați și vizualizați ”

Cu cheia API creată, faceți clic și copiați cheia, apoi faceți clic pe „ Terminat . ”

După aceea, adăugați încă 2 chei la fișier: „SENDGRID_DEFAULT_SENDER_ADDRESS” și „SENDGRID_DEFAULT_SENDER_NAME”. După cum indică numele, acestea sunt adresa de e-mail și numele pe care le vom folosi pentru orice e-mail trimis din aplicația noastră, dacă nu sunt înlocuite.

Notă: Pentru a face acest lucru, în Sender Authentication , asigurați-vă că scrie „Verified” în tabelul „Single Sender Verification”.

Setați detaliile de configurare a e-mailului aplicației

Pe lângă cheia API Twilio SendGrid, vom stoca și alte câteva setări globale de configurare a e-mailului. Mai exact, vom seta o adresă de e-mail și un nume de la și răspundem la care le vom folosi în fiecare mesaj de e-mail. În acest fel, nu trebuie să le setăm de fiecare dată.

De asemenea, vom crea 2 șabloane de corp de e-mail: unul pentru e-mailurile cu text simplu și unul pentru e-mailurile HTML. Pentru a face asta, în „config/autoload” creați un nou fișier numit „mail.global.php” și în el, adăugați următorul cod.

Creați o clasă pentru a instanția un obiect de e-mail

Cu detaliile cheie de configurare a aplicației setate, acum să creăm o clasă care va instanția un obiect de corespondență de bază cu proprietățile implicite setate. Pentru a face asta, într-un director nou, „src/App/src/Mailer”, creați un fișier nou numit „SendGridMailMessageFactory.php” și în el, adăugați codul de mai jos.

Când invocăm clasa, aceasta are acces la containerul de injecție de dependență (DI) al aplicației, din care va prelua detaliile de configurare pe care le-am stocat în „config/autoload/mail.global.php”.

După aceea, va instanția un nou obiect „SendGrid\Mail\Mail” și va seta detaliile de la și răspunsul la detalii, trecând detaliile de configurare respective apelurilor către metodele „Mail”, „setFrom” și, respectiv, „setReplyTo”. După aceea, va returna obiectul „Mail” instanțiat.

Pentru a-l folosi, totuși, trebuie să îl înregistrați cu containerul DI. Pentru a face asta, în „src/App/src/ConfigProvider”, adăugați următoarea intrare la elementul „factories” din matricea returnată de metoda „getDependencies”.

Creați un Handler pentru a trimite e-mail

În continuare trebuie să creăm o clasă Handler pentru compunerea și trimiterea de e-mailuri. Pentru a face asta, vom folosi instrumentul CLI al lui Mezzio , disponibil prin Composer, rulând comanda de mai jos.

Rularea comenzii de mai sus face patru lucruri pentru noi:

  1. Creează o nouă clasă Handler, „src/App/Handler/EmailSenderHandler.php ”
  2. Creează o clasă din fabrică pentru a instanția clasa Handler, „src/App/Handler/EmailSenderHandlerFactory.php”
  3. Creează un fișier șablon („src/App/templates/app/email-sender.html.<ext>”), de care nu vom avea nevoie . Numele fișierului „<ext>” este determinat de motorul de șablon pe care l-ați ales în timpul etapei „creare-proiect”.
  4. Înregistrează noua clasă Handler ca serviciu în containerul DI adăugând o intrare la „config/autoload/mezzio-tooling-factories.global.php”

Refactorizează Handler-ul pentru a trimite e-mailuri

Cu „EmailSenderHandler.php” creat, acum trebuie să-l refactorăm astfel încât să poată trimite e-mailuri. Pentru a face asta, vom refactoriza mai întâi constructorul „EmailSenderHandler”, înlocuind parametrul „TemplateRendererInterface” cu 3 parametri noi. Acestea vor inițializa 3 noi variabile ale membrilor clasei:

  • Un obiect „\SendGrid\Mail\Mail”.
  • Un obiect „\SendGrid”.
  • O matrice care conține detaliile de configurare necesare

Puteți vedea constructorul revizuit în exemplul de mai jos, împreună cu variabilele asociate membrilor clasei. Înlocuiți variabila existentă a membrului clasei și constructorul cu acest cod.

Notă: În continuare, trebuie să refactorăm metoda „mâner”. Înlocuiți conținutul existent al metodei de „mânere” „EmailSenderHandler” cu codul de mai jos, apoi să trecem prin ceea ce face.

Începe prin utilizarea „$request->getParsedBody()” pentru a prelua orice parametri furnizați în corpul cererii, care va returna o matrice asociativă, inițialând „$details”. Cu parametrii disponibili, apelează metoda „addTo” a obiectului „SendGrid\Mail\Mail” pentru a seta destinatarul e-mailului, trecând adresa de e-mail și numele destinatarului în primele 2 argumente și o serie de substituții în al treilea argument.

Înlocuirile vă permit să personalizați mesajele de e-mail pentru fiecare destinatar. În e-mailurile cu text simplu, orice șir imediat înconjurat de cratime, de exemplu, „-first_name-” este o înlocuire. În e-mailurile HTML, folosește sintaxa Handlebars , care înconjoară șiruri de caractere cu două paranteze, de exemplu, „{{ first_name }}”.

Apoi, setăm subiectul mesajului și adăugăm un text simplu și corpul mesajului HTML. Cu aceasta, e-mailul nostru este gata de trimis. Așa că folosim obiectul „SendGrid”, „$this->mailer”, pentru a-l trimite, inițialând o nouă variabilă, „$response”, cu răspunsul de la încercarea de a trimite mesajul. În cele din urmă, returnăm un obiect JsonResponse , care conține codul de stare și corpul răspunsului.

Notă: Refactorizează metoda __invoke a lui EmailSenderHandlerFactory

Acum că am finalizat refactorizarea „EmailSenderHandler”, trebuie să refactorăm „EmailSenderHandlerFactory”. Acest lucru va instanția corect „EmailSenderHandler”. Pentru a face acest lucru, înlocuiți definiția existentă a metodei sale „__invoke`” cu următorul cod.

Aceasta preia un obiect „\SendGrid\Mail\Mail” din containerul DI, preinițializat cu expeditorul și răspunsul la detaliile de e-mail și inițializează un nou obiect numit „$message”. Apoi instanțează un nou obiect „SendGrid”, numit „$mailer” pentru trimiterea mesajului de e-mail. În cele din urmă, preia configurația de e-mail din configurația aplicației. Apoi, le folosește pentru a inițializa și a returna obiectul „EmailSenderHandler”.

Actualizați tabelul de rutare

Cu toate aceste modificări, trebuie făcută o ultimă modificare înainte să putem testa codul și să trimitem un e-mail. Trebuie să actualizăm tabelul de rutare, astfel încât ruta implicită să folosească noua noastră clasă Handler ca handler al rutei, în loc de „HomePageHandler”. Pentru a face asta, înlocuiți definiția rutei implicite din „config/routes.php” cu următorul exemplu.

Trimite primul e-mail

Acum este timpul să trimiteți primul e-mail. Pentru a face asta, mai întâi, porniți aplicația rulând comanda de mai jos în terminal.

Apoi, folosind cURL, faceți o solicitare GET către „ http://localhost:8080 ”, ca în exemplul de mai jos, înlocuind valorile dintre paranteze unghiulare cu detalii relevante pentru e-mailul dvs.

Ar trebui să vedeți „{“status”:202,“message”:””}” în terminal și ar trebui să primiți un e-mail care arată ca imaginea de mai jos.

Notă: Utilizați șabloane de e-mail tranzacționale în loc de șiruri de șabloane

Deși am reușit să trimitem un e-mail atât cu un text simplu, cât și cu un corp HTML, modul în care am făcut-o, totuși, este mai puțin decât ideal. Pentru fiecare e-mail pe care îl trimitem – și aplicația noastră poate ajunge să trimită destul de multe – va trebui să le adăugăm un text simplu și un corp HTML.

Dar stocarea definițiilor corpului de e-mail în cod plasează majoritatea efortului echipei de dezvoltare. Cu toate acestea, cel puțin din experiența mea, se întâmplă adesea ca alte echipe, adesea de marketing, să creeze și să întrețină șabloane de e-mail.

Deci, din acest motiv și pentru că ar accelera dezvoltarea și ar împărți încărcarea în mai multe echipe, vom refactoriza aplicația pentru a folosi șabloane de e-mail tranzacționale . Le puteți crea și menține prin interfața de utilizare Twilio SendGrid de către membrii echipei care pot avea puțină sau deloc experiență tehnică, în loc de cod.

Dacă nu ați auzit de ele, glosarul Twilio SendGrid le definește după cum urmează:

Șabloanele de e-mail tranzacționale sunt machete de e-mail precodate pe care agenții de marketing, designerii și dezvoltatorii le pot folosi pentru a crea rapid și ușor campanii de e-mail tranzacționale. Șabloanele de e-mail tranzacționale ale Twilio SendGrid permit persoanelor netehnice și tehnice deopotrivă să facă modificări în timp real la e-mailurile primite de destinatarii lor.

Pentru acest articol, avem nevoie doar de unul destul de simplu. Pentru a face asta, urmați detaliile din documentația Twilio SendGrid și creați unul care să aibă ca conținut doar într-un singur modul text. Apoi, pentru corpul textului, utilizați textul de mai jos.

Rețineți că există 6 înlocuiri în e-mail:

  • „first_name”: prenumele clientului
  • „last_name”: numele de familie al clientului
  • „sender_name”: numele magazinului de comerț electronic (The Little PHP Shop)
  • „sender_state”: starea magazinului de comerț electronic
  • „sender_country”: țara magazinului de comerț electronic
  • „support_email”: e-mailul de asistență pe care clienții îl pot folosi pentru a obține asistență post-vânzare

Având în vedere acest lucru, trebuie să punem acele informații la dispoziția aplicației noastre. Numele și prenumele clientului le avem deja. Restul de 4 înlocuiri vor fi globale, așa că așa cum am făcut mai devreme, vom adăuga configurația de mai jos la „ config/autoload/mail.global.php ”, după elementul „șabloane”.

Cu noul fișier de configurare creat, în metoda „Handle” „EmailSenderHandler”, înlocuiți cele 2 apeluri la „$this->mail->addContent(),” cu următorul cod.

Cele 2 apeluri de metodă adaugă detaliile expeditorului și adresa de e-mail de suport ca înlocuiri globale. Aceste înlocuiri se aplică corpului de e-mail înainte de orice alte înlocuiri, dar sunt înlocuite dacă există înlocuiri cu aceeași cheie pentru un destinatar de e-mail.

Apoi, trebuie să preluați ID-ul șablonului de e-mail tranzacțional. Îl puteți găsi făcând clic pe numele șablonului din lista de șabloane , așa cum puteți vedea în captura de ecran de mai jos.

Copiați-l și stocați-l în „config/autoload/mail.global.php” într-un element nou cu cheia „template_id” și apoi eliminați „plain” și „HTML”. Când ați terminat, elementul „mail/șabloane” al matricei returnate va arăta ca codul de mai jos, unde „<id-ul șablonului>” înlocuiește ID-ul șablonului.

Cu configurația actualizată, acum trebuie să adăugăm un apel la metoda „Mail” „setTemplateId” în metoda „handle” „EmailSenderHandler”, trecând ID-ul șablonului pe care tocmai l-am adăugat la „config/autoload/mail.global”. php.” Puteți vedea un exemplu în codul de mai jos.

Să testăm modificările

Ca și înainte, folosind cURL, faceți o solicitare GET către „ http://localhost:8080 ” pentru a testa dacă modificările funcționează conform așteptărilor. Ar trebui să vedeți „{“status”:202,“message”:””}” ieșit la terminal, ca în exemplul anterior. În căsuța de e-mail, ar trebui să vedeți un e-mail minunat, cu înlocuirile înlocuite, ca în captura de ecran de mai jos.

Atașați o factură PDF

Acum că folosim șabloane dinamice, să atașăm factura PDF despre care am vorbit în partea de sus a articolului. Pentru a vă economisi timpul și efortul de a căuta sau de a crea unul singur, am creat un exemplu de factură PDF pe care o puteți folosi pentru acest articol. Salvați-l în directorul „date” al aplicației .

Notă: Pentru a atașa o factură, trebuie să folosim metoda „Mail” „addAttachment”, pe care o puteți vedea în următorul exemplu de cod. Metoda ia 5 argumente, dar furnizăm doar primele 4. Acestea sunt:

  1. Un obiect „Atașament” sau șir codificat Base64 . Dacă valoarea acestui parametru nu este codificată în base64, metoda va face asta pentru noi.
  2. Tipul mime al atașamentului (cunoscut acum ca tip media ).
  3. Numele fișierului atașat . Acesta este numele pe care fișierul îl va salva în mod implicit, cu excepția cazului în care utilizatorul îl schimbă.
  4. Dispunerea conținutului atașamentului . Dacă nu sunteți familiarizat cu dispoziția conținutului, dispoziția conținutului în linie înseamnă că atașarea ar trebui să se afișeze automat când se afișează mesajul, iar dispoziția conținutului atașamentului înseamnă că atașarea nu se afișează automat și necesită o anumită formă de acțiune din partea utilizatorului. deschidel.

În exemplul de cod de mai jos, metoda PHP file_get_contents citește conținutul fișierului într-o nouă variabilă numită „$invoice”. Apoi, PDF-ul se atașează la mesaj apelând metoda „addAttachment”.

Aici noi:

  • Introduceți conținutul facturii, care va fi codificată Base64
  • Setați tipul MIME la „application/pdf” în timp ce atașăm un fișier PDF
  • Setați numele fișierului facturii la un nume fictiv la care un client s-ar putea aștepta în mod rezonabil
  • Setați dispoziția conținutului la „atașament”

Acum că am terminat aceste modificări, să testăm dacă funcționează. Rulați aceeași solicitare cURL pe care am rulat-o de 2 ori anterioare. Apoi, în căsuța de e-mail, ar trebui să vedeți un e-mail minunat cu exemplul de factură PDF vizibilă atunci când vizualizați e-mailul.

Așa se trimite e-mailuri cu PHP folosind Twilio SendGrid și Mezzio

Deși am zgâriat doar suprafața a ceea ce este posibil atunci când trimitem e-mailuri cu Twilio SendGrid și Mezzio, acum puteți trimite un e-mail cu un text simplu și un corp HTML, precum și cu un atașament. De asemenea, ați învățat cum să utilizați șabloane tranzacționale și substituții pe care le puteți seta la nivel global și pentru fiecare destinatar.

Vă încurajez cu tărie să aruncați o privire la documentația bibliotecii PHP pentru a vedea ce altceva este disponibil, cum ar fi programarea trimiterilor de e-mail, atașarea unui fișier de pe Amazon S3, adăugarea antetelor și adăugarea de secțiuni și categorii.

Matthew Setter este editor PHP în echipa Twilio Voices și, bineînțeles, dezvoltator PHP. El este și autorul cărții Mezzio Essentials . Când nu scrie cod PHP, editează articole excelente PHP aici, la Twilio. El poate fi contactat prin:

  • E-mail: [email protected]
  • Web: http://matthewsetter.com
  • Twitter: @settermjd
  • GitHub: https://github.com/settermjd