Jak wysłać e-mail za pomocą PHP za pomocą Twilio SendGrid i Mezzio?

Opublikowany: 2021-03-24

Poczta e-mail jest tak samo ważnym narzędziem komunikacji jak zawsze. Aby pomóc Ci lepiej wykorzystać pocztę elektroniczną, pokażę Ci, jak wysyłać wiadomości e-mail za pomocą frameworka Mezzio PHP i API Twilio SendGrid.

W szczególności dowiesz się, jak wysyłać wiadomości e-mail z treściami w postaci zwykłego tekstu i HTML, w tym z załącznikiem PDF. Dowiesz się również, jak korzystać z funkcji szablonów transakcyjnych Twilio SendGrid, aby uprościć tworzenie treści wiadomości e-mail zarówno przez zespół programistów, jak i każdy inny zespół w Twojej organizacji.

Brzmi dobrze? Zaczynajmy.

Szybki przegląd aplikacji

Aby uczynić ten samouczek bardziej znaczącym, udawaj, że kod, który napiszemy, jest częścią fikcyjnego, internetowego sklepu e-commerce zbudowanego za pomocą Mezzio, o nazwie The Little PHP Shop — a konkretnie części bezpośrednio po dokonaniu przez klienta zakupu. Na tym etapie przepływu użytkownika klient otrzymuje wiadomość e-mail z podziękowaniem za zakup i dołącza do swojej dokumentacji fakturę PDF.

Zamierzamy utworzyć klasę Handler, aby wysłać wiadomość e-mail po zakupie, która otrzyma szczegóły zakupu z zamówienia zrealizowanego przez klienta. Dzięki tym informacjom o zakupie klasa Handler użyje kilku klas w interfejsie API SendGrid PHP do zbudowania i wysłania wiadomości e-mail z potwierdzeniem zakupu.

Spośród nich najważniejsze to „SendGrid\Mail\Mail” i „\SendGrid”. „SendGrid\Mail\Mail” to obiekt przechowujący wszystkie właściwości wiadomości e-mail, którą wyślemy za pośrednictwem usługi Twilio SendGrid. Obiekt „SendGrid” tworzy warstwę transportową, ułatwiając wysyłanie wiadomości e-mail przez Twilio SendGrid.

Warunki wstępne

Aby ukończyć ten samouczek, będziesz potrzebować następujących 4 rzeczy w lokalnym środowisku programistycznym:

  1. Konto Twilio SendGrid
  2. PHP 7.4 z zainstalowanymi i włączonymi rozszerzeniami cURL , mbstring i Open SSL
  3. Composer zainstalowany na całym świecie
  4. kędzior

Rusztuj aplikację Mezzio

Najpierw musimy stworzyć aplikację bazową. Aby to zrobić, jak zwykle użyjemy szkieletu Mezzio , aby zrobić to za nas. Gdy już stworzymy szkielet aplikacji bazowej, przełączymy się do nowo utworzonego katalogu projektu. Następnie uruchom następujące polecenia w swoim terminalu, postępując zgodnie z monitami dotyczącymi pierwszego:

Zainstaluj wymagane zależności

Z rusztowaniem projektu musimy dodać 3 dodatkowe zależności, aby ukończyć projekt. To są:

  • Biblioteka PHP API Twilio SendGrid do interakcji z API Twilio SendGrid
  • Klient PHP HTTP do wysyłania żądań HTTP
  • PHP Dotenv do przechowywania i pobierania zmiennych środowiskowych

Aby je zainstalować, uruchom następujące polecenie w swoim terminalu:

Zainicjuj PHP Dotenv

Po zainstalowaniu zależności ładujemy PHP Dotenv, aby odczytał zmienne ustawione w „.env” i udostępnił je PHP jako zmienne środowiskowe. Aby to zrobić, wstaw następujący kod w „public/index.php”, zaraz po „require vendor/autoload.php”.

Dodaj dane swojego konta Twilio SendGrid

Teraz musisz dostarczyć aplikacji swój klucz API SendGrid. Aby to zrobić, po zalogowaniu się do Twilio SendGrid przejdź do „Ustawienia -> Klucze API . " Raz tam:

  1. Kliknij „ Utwórz klucz API ”, aby utworzyć klucz API
  2. Nadaj nazwę nowemu kluczowi API, zaakceptuj domyślne uprawnienia klucza API „ Pełny dostęp ” i kliknij „ Utwórz i wyświetl ”

Po utworzeniu klucza API kliknij i skopiuj klucz, a następnie kliknij „ Gotowe . ”

Następnie dodaj 2 kolejne klucze do pliku: „SENDGRID_DEFAULT_SENDER_ADDRESS” i „SENDGRID_DEFAULT_SENDER_NAME”. Jak wskazują nazwy, są to adresy e-mail i imię i nazwisko, których będziemy używać we wszelkich wiadomościach e-mail wysyłanych z naszej aplikacji, chyba że zostaną one zastąpione.

Uwaga: Aby to zrobić, w Uwierzytelnianiu nadawcy upewnij się, że w tabeli „Weryfikacja pojedynczego nadawcy” jest napisane „Zweryfikowano”.

Ustaw szczegóły konfiguracji poczty aplikacji

Oprócz klucza interfejsu API Twilio SendGrid będziemy przechowywać kilka innych globalnych ustawień konfiguracji poczty. W szczególności ustawimy adres e-mail nadawcy i adres e-mail oraz imię i nazwisko, których będziemy używać w każdej wiadomości e-mail. W ten sposób nie musimy ich ustawiać za każdym razem.

Zamierzamy również utworzyć 2 szablony treści wiadomości e-mail: jeden dla wiadomości e-mail w postaci zwykłego tekstu i jeden dla wiadomości e-mail w formacie HTML. Aby to zrobić, w „config/autoload” utwórz nowy plik o nazwie „mail.global.php” i dodaj w nim następujący kod.

Utwórz klasę, aby utworzyć instancję obiektu poczty

Mając ustawione kluczowe szczegóły konfiguracji aplikacji, utwórzmy teraz klasę, która będzie tworzyć instancję podstawowego obiektu poczty z domyślnymi ustawieniami właściwości. Aby to zrobić, w nowym katalogu „src/App/src/Mailer” utwórz nowy plik o nazwie „SendGridMailMessageFactory.php” i dodaj do niego poniższy kod.

Kiedy wywołujemy klasę, ma ona dostęp do kontenera wstrzykiwania zależności (DI) aplikacji, z którego pobiera szczegóły konfiguracji, które zapisaliśmy w „config/autoload/mail.global.php”.

Następnie utworzy instancję nowego obiektu „SendGrid\Mail\Mail” i ustawi od oraz odpowie na szczegóły, przekazując odpowiednie szczegóły konfiguracji do wywołań odpowiednio metod „Mail”, „setFrom” i „setReplyTo”. Następnie zwróci skonkretyzowany obiekt „Mail”.

Aby jednak z niego skorzystać, musisz zarejestrować go w kontenerze DI. Aby to zrobić, w „src/App/src/ConfigProvider” dodaj następujący wpis do elementu „factories” w tablicy zwróconej przez metodę „getDependencies”.

Utwórz Handler, aby wysłać e-mail

Następnie musimy stworzyć klasę Handler do tworzenia i wysyłania e-maili. Aby to zrobić, użyjemy narzędzia Mezzio CLI , dostępnego w Composer, uruchamiając poniższe polecenie.

Uruchomienie powyższego polecenia robi dla nas cztery rzeczy:

  1. Tworzy nową klasę Handler, „src/App/Handler/EmailSenderHandler.php ”
  2. Tworzy klasę fabryczną w celu utworzenia instancji klasy Handler „src/App/Handler/EmailSenderHandlerFactory.php”
  3. Tworzy plik szablonu („src/App/templates/app/email-sender.html.<ext>”), którego nie będziemy potrzebować . Nazwa pliku „<ext>” jest określana przez silnik szablonów wybrany na etapie „tworzenia projektu”.
  4. Rejestruje nową klasę Handler jako usługę w kontenerze DI, dodając wpis do „config/autoload/mezzio-tooling-factories.global.php”

Refaktoryzuj Handler, aby wysyłać e-maile

Po utworzeniu „EmailSenderHandler.php” musimy teraz zrefaktoryzować go, aby mógł wysyłać e-maile. W tym celu najpierw dokonamy refaktoryzacji konstruktora „EmailSenderHandler”, zastępując parametr „TemplateRendererInterface” 3 nowymi parametrami. Spowodują one zainicjowanie 3 nowych zmiennych składowych klasy:

  • Obiekt „\SendGrid\Mail\Mail”
  • Obiekt „\SendGrid”
  • Tablica zawierająca wymagane szczegóły konfiguracji

Możesz zobaczyć poprawiony konstruktor w poniższym przykładzie, wraz z powiązanymi zmiennymi składowymi klasy. Zastąp istniejącą zmienną składową klasy i konstruktora tym kodem.

Uwaga: Następnie musimy dokonać refaktoryzacji metody „uchwytu”. Zastąp istniejącą zawartość metody „EmailSenderHandler” „handle” poniższym kodem, a następnie przejdźmy przez to, co robi.

Rozpoczyna się od użycia „$request->getParsedBody()”, aby pobrać dowolne parametry podane w treści żądania, które zwróci tablicę asocjacyjną, inicjując „$details”. Mając dostępne parametry, wywołuje metodę „addTo” obiektu „SendGrid\Mail\Mail”, aby ustawić odbiorcę wiadomości e-mail, przekazując adres e-mail i nazwę odbiorcy w pierwszych 2 argumentach oraz tablicę podstawień w trzecim argumencie.

Zastępstwa pozwalają dostosować wiadomości e-mail dla każdego odbiorcy. W wiadomościach e-mail w postaci zwykłego tekstu każdy ciąg bezpośrednio otoczony myślnikami, np. „-first_name-” jest substytucją. W wiadomościach e-mail HTML używa składni Handlebars , która otacza ciągi z podwójnymi nawiasami, np. „{{ first_name }}”.

Następnie ustawiamy temat wiadomości i dodajemy tekst jawny oraz treść wiadomości HTML. Dzięki temu nasz e-mail jest gotowy do wysłania. Używamy więc obiektu „SendGrid”, „$this->mailer”, aby go wysłać, inicjując nową zmienną „$response” z odpowiedzią z próby wysłania wiadomości. Na koniec zwracamy obiekt JsonResponse zawierający kod statusu i treść odpowiedzi.

Uwaga: Refactor EmailSenderHandlerFactory metoda __invoke

Teraz, gdy zakończyliśmy refaktoryzację „EmailSenderHandler”, musimy dokonać refaktoryzacji „EmailSenderHandlerFactory”. Spowoduje to prawidłowe utworzenie instancji „EmailSenderHandler”. Aby to zrobić, zastąp istniejącą definicję metody „__invoke`” następującym kodem.

Pobiera to obiekt „\SendGrid\Mail\Mail” z kontenera DI, wstępnie zainicjowany z nadawcą i odpowiedzią na szczegóły wiadomości e-mail oraz inicjuje nowy obiekt o nazwie „$message”. Następnie tworzy instancję nowego obiektu „SendGrid” o nazwie „$mailer” do wysyłania wiadomości e-mail. Na koniec pobiera konfigurację poczty z konfiguracji aplikacji. Następnie używa ich do inicjalizacji i zwrócenia obiektu „EmailSenderHandler”.

Zaktualizuj tablicę routingu

Po tych wszystkich zmianach należy wprowadzić jeszcze jedną zmianę, zanim będziemy mogli przetestować kod i wysłać e-mail. Musimy zaktualizować tablicę routingu, aby domyślna trasa używała naszej nowej klasy Handler jako procedury obsługi trasy, zamiast „HomePageHandler”. Aby to zrobić, zastąp definicję trasy domyślnej w „config/routes.php” następującym przykładem.

Wyślij pierwszego e-maila

Teraz nadszedł czas na wysłanie pierwszego e-maila. Aby to zrobić, najpierw uruchom aplikację, uruchamiając poniższe polecenie w terminalu.

Następnie, korzystając z cURL, wyślij żądanie GET do „ http://localhost:8080 ”, jak w poniższym przykładzie, zastępując wartości w nawiasach ostrych odpowiednimi szczegółami wiadomości e-mail.

Powinieneś zobaczyć wyjście „{„status”:202,„wiadomość”:””}” na terminalu i powinieneś otrzymać wiadomość e-mail, która wygląda jak na poniższym obrazku.

Uwaga: Używaj szablonów transakcyjnych wiadomości e-mail zamiast ciągów szablonów

Chociaż byliśmy w stanie wysłać wiadomość e-mail zarówno w postaci zwykłego tekstu, jak i treści HTML, sposób, w jaki to zrobiliśmy, nie jest jednak idealny. Do każdego wysyłanego przez nas e-maila — a nasza aplikacja może w końcu wysłać całkiem sporo — musimy dodać dla nich zwykły tekst i treść HTML.

Jednak przechowywanie definicji treści wiadomości e-mail w kodzie nakłada większość wysiłku na zespół programistów. Jednak, przynajmniej z mojego doświadczenia, często zdarza się, że inne zespoły, często marketingowe, tworzą i utrzymują szablony e-maili.

Z tego powodu, a także ponieważ przyspieszyłoby to rozwój i dzielenie obciążenia między wiele zespołów, zamierzamy zrefaktoryzować aplikację tak, aby korzystała z szablonów transakcyjnych wiadomości e-mail . Możesz je tworzyć i konserwować za pomocą interfejsu użytkownika Twilio SendGrid przez członków zespołu, którzy mogą mieć niewielkie lub żadne doświadczenie techniczne, zamiast w kodzie.

Jeśli nie słyszałeś o nich, glosariusz Twilio SendGrid definiuje je w następujący sposób:

Szablony transakcyjnych wiadomości e-mail to wstępnie zakodowane układy wiadomości e-mail, których marketerzy, projektanci i programiści mogą używać do szybkiego i łatwego tworzenia transakcyjnych kampanii e-mailowych. Szablony transakcyjnych wiadomości e-mail Twilio SendGrid umożliwiają osobom nietechnicznym i technicznym wprowadzanie zmian w czasie rzeczywistym w wiadomościach e-mail otrzymywanych przez ich odbiorców.

W tym artykule potrzebujemy tylko dość podstawowego. Aby to zrobić, postępuj zgodnie ze szczegółami w dokumentacji Twilio SendGrid i utwórz taki, który ma jako swoją zawartość tylko w module jednotekstowym. Następnie jako tekst podstawowy użyj poniższego tekstu.

Zwróć uwagę, że w e-mailu znajduje się 6 podmian:

  • „first_name”: imię klienta
  • „last_name”: Nazwisko klienta
  • „sender_name”: nazwa sklepu internetowego (The Little PHP Shop)
  • „sender_state”: Stan sklepu internetowego
  • „sender_country”: kraj sklepu internetowego
  • „support_email”: adres e-mail pomocy technicznej, z którego klienci mogą korzystać, aby uzyskać wsparcie posprzedażowe

Biorąc to pod uwagę, musimy udostępnić te informacje naszej aplikacji. Imiona i nazwiska klienta już znamy. Pozostałe 4 podstawienia będą globalne, więc tak jak to zrobiliśmy wcześniej, dodamy poniższą konfigurację do „ config/autoload/mail.global.php ”, po elemencie „templates”.

Po utworzeniu nowego pliku konfiguracyjnego w metodzie „EmailSenderHandler” „handle” zastąp 2 wywołania „$this->mail->addContent()” następującym kodem.

Dwa wywołania metod dodają dane nadawcy i obsługują adres e-mail jako globalne podstawienia. Te podstawienia dotyczą treści wiadomości e-mail przed innymi podstawieniami, ale są zastępowane, jeśli istnieją podstawienia z tym samym kluczem dla odbiorcy wiadomości e-mail.

Następnie musisz pobrać identyfikator szablonu transakcyjnego e-maila. Możesz go znaleźć, klikając nazwę szablonu na liście szablonów , jak widać na poniższym zrzucie ekranu.

Skopiuj go i przechowuj w „config/autoload/mail.global.php” w nowym elemencie z kluczem „template_id”, a następnie usuń „plain” i „HTML”. Po zakończeniu element „mail/templates” zwróconej tablicy będzie wyglądał jak poniższy kod, gdzie „<identyfikator szablonu>” zastępuje identyfikator szablonu.

Po zaktualizowaniu konfiguracji musimy teraz dodać wywołanie metody „Mail” „setTemplateId” w metodzie „EmailSenderHandler” „handle”, przekazując identyfikator szablonu, który właśnie dodaliśmy do „config/autoload/mail.global”. php.” Możesz zobaczyć przykład w poniższym kodzie.

Przetestujmy zmiany

Tak jak poprzednio, używając cURL, wyślij żądanie GET do „ http://localhost:8080 ”, aby sprawdzić, czy zmiany działają zgodnie z oczekiwaniami. Powinieneś zobaczyć wyjście „{„status”:202,„wiadomość”:””}” na terminalu, tak jak w poprzednim przykładzie. W skrzynce odbiorczej e-mail powinien pojawić się piękny e-mail z zastąpionymi zastąpieniami, jak na poniższym zrzucie ekranu.

Dołącz fakturę PDF

Teraz, gdy korzystamy z szablonów dynamicznych, dołączmy fakturę PDF, o której mówiliśmy na początku artykułu. Aby zaoszczędzić czas i wysiłek związany z samodzielnym poszukiwaniem lub tworzeniem faktury, przygotowałem przykładową fakturę PDF , której możesz użyć w tym artykule. Zapisz go w katalogu „ data” aplikacji .

Uwaga: Aby dołączyć fakturę, musimy skorzystać z metody „Mail” „addAttachment”, którą można zobaczyć w kolejnym przykładzie kodu. Metoda przyjmuje 5 argumentów, ale dostarczamy tylko pierwsze 4. Są to:

  1. Obiekt „ Załącznik” lub ciąg zakodowany w Base64 . Jeśli wartość tego parametru nie jest zakodowana w base64, metoda zrobi to za nas.
  2. Typ MIME załącznika (obecnie znany jako typ mediów ).
  3. Nazwa pliku załącznika . Jest to nazwa, pod którą plik zostanie domyślnie zapisany, chyba że użytkownik ją zmieni.
  4. Dyspozycja zawartości załącznika . Jeśli nie jesteś zaznajomiony z dyspozycją zawartości, wbudowana dyspozycja zawartości oznacza, że ​​załącznik powinien być automatycznie wyświetlany po wyświetleniu wiadomości, a dyspozycja zawartości załącznika oznacza, że ​​załącznik nie jest wyświetlany automatycznie i wymaga jakiejś formy działania od użytkownika, aby Otwórz to.

W poniższym przykładzie kodu metoda PHP file_get_contents odczytuje zawartość pliku do nowej zmiennej o nazwie „$invoice”. Następnie plik PDF dołącza się do wiadomości, wywołując metodę „addAttachment”.

Tutaj my:

  • Przekaż treść faktury, która będzie zakodowana w Base64
  • Ustaw typ MIME na „aplikacja/pdf”, ponieważ dołączamy plik PDF
  • Ustaw nazwę pliku faktury na fikcyjną nazwę, której klient może racjonalnie oczekiwać
  • Ustaw dyspozycję zawartości na „załącznik”

Teraz, gdy zakończyliśmy te zmiany, sprawdźmy, czy działają. Uruchom to samo żądanie cURL, które uruchamialiśmy poprzednie 2 razy. Następnie w skrzynce odbiorczej e-mail powinien pojawić się piękny e-mail z przykładową fakturą PDF widoczną podczas przeglądania wiadomości e-mail.

Oto jak wysyłać wiadomości e-mail za pomocą PHP za pomocą Twilio SendGrid i Mezzio

Chociaż tylko zarysowaliśmy powierzchnię tego, co jest możliwe podczas wysyłania wiadomości e-mail za pomocą Twilio SendGrid i Mezzio, możesz teraz wysłać wiadomość e-mail ze zwykłym tekstem i treścią HTML, a także z załącznikiem. Nauczyłeś się również, jak korzystać z szablonów transakcyjnych i zamienników, które można ustawiać globalnie i na odbiorcę.

Gorąco zachęcam do zapoznania się z dokumentacją biblioteki PHP, aby zobaczyć, co jeszcze jest dostępne, takie jak planowanie wysyłek e-maili, załączanie pliku z Amazon S3, dodawanie nagłówków oraz dodawanie sekcji i kategorii.

Matthew Setter jest edytorem PHP w zespole Twilio Voices i – oczywiście – programistą PHP. Jest także autorem Mezzio Essentials . Kiedy nie pisze kodu PHP, edytuje świetne artykuły PHP w Twilio. Można się z nim skontaktować przez:

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