php email
v1.0.5
Bietet eine objektorientierte Möglichkeit, E-Mails zu senden und in die Warteschlange zu stellen.
In fast allen Projekten besteht die Notwendigkeit, E-Mails zu versenden, z. B. für die Benutzerregistrierung oder für Funktionen zum Zurücksetzen von Passwörtern. Die meisten versendeten E-Mails sind sehr einfach. Anspruchsvolle Funktionen wie PGP-Verschlüsselung usw. sind nicht erforderlich. Diese Bibliothek bietet eine Möglichkeit, solche E-Mails zu erstellen, ohne den PHPMailer (die zugrunde liegende Bibliothek) einzurichten, mehrere E-Mails zu versenden und sogar den E-Mail-Versand mithilfe einer datenbankgestützten Warteschlange zu verzögern – und das alles in einem objektorientierter Weg.
Merkmale sind:
EmailQueue Objekt.Dieses Projekt ist unter GNU LGPL 3.0 lizenziert.
composer install technicalguru/email
Sie können die Quellcodepakete von der GitHub-Release-Seite herunterladen
Die zentrale Klasse zur Konfiguration ist die EmailConfig . Es enthält alle notwendigen Informationen. Beginnen wir mit dem Grundgerüst:
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
Die obigen Zeilen erstellen die Konfiguration und weisen sie an, die Zeitzone Europe/Berlin zu verwenden, wenn Zeitstempel erstellt werden müssen. Dies ist vor allem dann erforderlich, wenn E-Mails in der Warteschlange stehen und der Zeitstempel aufgezeichnet werden muss. Dieser Wert ist optional und standardmäßig auf UTC eingestellt.
Als nächstes wird eine Standard-Absenderadresse konfiguriert. Der Standardabsender wird verwendet, wenn für eine bestimmte zu versendende E-Mail keine Absenderadresse definiert ist. Das Erstellen von E-Mail-Adressen wird weiter unten erläutert.
Das Betreff-Präfix wird in jeder E-Mail verwendet, die später versendet wird. Den Betreffzeilen wird diese Zeichenfolge vorangestellt. Der Standardwert ist NULL und der Betreff wird nicht geändert.
Eine Debug-Adresse ist nur erforderlich, wenn Sie eine Test-Mail senden müssen.
Wir müssen noch angeben, wo sich unser SMTP-Server befindet. So stellen Sie diese Werte ein:
use TgEmailConfigSmtpConfig;
$host = 'smtp.example.com;
$port = 587;
$auth = TRUE;
$username = 'mySmtpUser';
$password = 'mySmtpPassword';
$secureOption = 'starttls';
$smtpConfig = new SmtpConfig($host, $port, $auth, $username, $password, $secureOption);
$config->setSmtpConfig($smtpConfig);
Die meisten Optionen sind selbsterklärend. $auth teilt dem zugrunde liegenden PHPMailer mit, ob die Authentifizierung mit den angegebenen Benutzeranmeldeinformationen erfolgen soll. $secureOption wird von PHPMailer definiert und muss den Wert smtps oder starttls haben. Weitere Informationen finden Sie in der PHPMailer-Dokumentation.
Alle Eigenschaften können mithilfe eines Setters festgelegt werden:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
Authentifizierungsdaten können auch mithilfe der Schnittstelle TgUtilsAuthCredentialsProvider aus dem Paket technicalguru/utils festgelegt werden:
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
Jetzt ist es an der Zeit, unser zentrales MailQueue Objekt zu erstellen:
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
Sie sind bereit, Ihre erste E-Mail zu senden.
Es gibt eine schnelle und einfache Möglichkeit, zu überprüfen, ob Ihr Setup korrekt funktioniert:
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
Wir haben die Mindestanforderungen zum Versenden einer E-Mail festgelegt:
use TgEmailEmail;
$email = new Email();
$email
->setSubject('Hello World')
->addTo('[email protected]', 'John Doe')
->addBcc('[email protected]')
->setReplyTo('[email protected]')
->setBody(Email::TEXT, 'The text e-mail body')
->setBody(Email::HTML, '<p>The HTML e-mail body</p>');
// Will return FALSE when sending fails
$rc = $mailer->send($email);
Das ist es. Der obige Codeausschnitt ist alles, was Sie in Ihrem Anwendungscode zum Versenden von E-Mails benötigen. Konfiguration und Einrichtung müssen irgendwo in Ihrem Infrastruktur-Setup vergraben sein.
Das Anhängen von Dateien oder das Einbetten von Bildern ist einfach. Sie müssen die Datei im Dateisystem verfügbar und lesbar haben:
use TgEmailAttachment;
$myFile = new Attachment(Attachment::ATTACHED, 'file.pdf', NULL, '/local/path/to/file.pdf', 'application/pdf');
$myImage = new Attachment(Attachment::EMBEDDED, 'img.png', 'img1', '/local/path/to/img.png', 'image/png');
$email
->addAttachment($myFile)
->addAttachment($myImage);
Beachten Sie den dritten Parameter eingebetteter Bilder. Es definiert eine eindeutige ID in Ihrer HTML-E-Mail, auf die Sie verweisen können
// Using the embedded image
$myHTML = '<img src="cid:img1">';
Die MailQueue lässt alle Ihre Anhänge in Ihrem Dateisystem unberührt. Manchmal möchten Sie die Datei jedoch möglicherweise löschen, nachdem Sie die E-Mail gesendet haben. Der Konstruktor benötigt zwei zusätzliche Argumente:
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
Der erste boolesche Wert löst das Löschen der Datei aus, nachdem die E-Mail erfolgreich gesendet wurde. Der zweite boolesche Wert gibt an, ob die Datei gelöscht werden kann, wenn das Senden fehlschlägt. Mit diesen Parametern müssen Sie sich nicht mehr um temporäre Dateien kümmern. Vor allem, wenn es um Warteschlangen und verzögertes Senden geht.
MailQueue unterstützt sogenannte Mail-Modi. Sie teilen dem Mailer-Objekt mit, wie E-Mails generell zu behandeln sind. Dies ist praktisch, wenn Sie entweder ein Setup testen, sich in einer Umgebung befinden, die über echte E-Mail-Adressen verfügt (z. B. Benutzerakzeptanztestumgebungen) oder wenn das tatsächliche Versenden von E-Mails keinen großen Sinn ergibt.
Diese Modi sind verfügbar:
EmailQueue::DEFAULT – Dies ist der normale Vorgang. Alle E-Mails werden wie definiert versendet.EmailQueue::BLOCK – Dadurch wird verhindert, dass E-Mails gesendet oder in die Warteschlange gestellt werden. Der Rückkehrcode ist immer TRUE.EmailQueue::REROUTE – Alle E-Mails werden an eine andere Adresse gesendet, normalerweise eine Administrator- oder Entwickleradresse, und die definierten Empfänger der E-Mail werden ignoriert.EmailQueue::BCC – Die E-Mails werden an die vorgesehenen Empfänger gesendet, aber zusätzliche Adressen sind auf BCC eingestellt.Das Blockieren aller zu sendenden oder in die Warteschlange gestellten E-Mails ist ganz einfach:
$mailer->setMailMode(EmailQueue::BLOCK);
Die gleiche Methode kann für das zentrale EmailConfig Objekt verwendet werden.
Sie müssen eine RerouteConfig Konfiguration in der Hauptkonfiguration festlegen. Sie können dies im Voraus beim Erstellen des Konfigurationsobjekts oder insgesamt beim Festlegen des E-Mail-Modus festlegen:
use TgEmailConfigRerouteConfig;
// Create the config
$subjectPrefix = '[Rerouted]';
$recipients = array('[email protected]');
$rerouteConfig = new RerouteConfig($subjectPrefix, $recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::REROUTE, $rerouteConfig);
Sie müssen eine BccConfig -Konfiguration in der Hauptkonfiguration festlegen. Sie können dies im Voraus beim Erstellen des Konfigurationsobjekts oder insgesamt beim Festlegen des E-Mail-Modus festlegen:
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
Ein Nachteil des Versendens von E-Mails direkt aus dem Anwendungscode besteht darin, dass es zeitaufwändig ist. Ihr Benutzer muss warten, bis der Versand abgeschlossen ist, bevor er eine Antwort von Ihrer Bewerbung sehen kann. Die Lösung besteht darin, E-Mails in die Warteschlange zu stellen, da der Versand verzögert wird (vorzugsweise einem Cron-Job) und der Benutzer seine/seine Antwort auf die Bewerbung schnell erhält.
Sie benötigen ein TgDatabaseDatabase Objekt, um E-Mails in die Warteschlange zu stellen. Andernfalls löst EmailQueue Ausnahmen aus, wenn Sie versuchen, E-Mails in die Warteschlange zu stellen. Informationen zum Erstellen des Database finden Sie in der TgDatabaseDatabase Dokumentation. Richten Sie das entsprechende EmailsDAO und EmailQueue wie folgt ein:
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
Der Mailer erstellt automatisch die Warteschlangentabelle, wenn sie nicht vorhanden ist.
Sobald das EmailsDAO verfügbar ist, können Sie E-Mails ganz einfach in die Warteschlange stellen:
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
Sie können die Warteschlange in einem weiteren Aufruf oder während eines Cronjobs bearbeiten:
$mailer->processQueue($maxSeconds);
Das Argument $maxSeconds stellt sicher, dass die Verarbeitung stoppt, wenn das Zeitlimit erreicht ist. Das Argument ist optional und beträgt standardmäßig 60 Sekunden.
Es gibt mehrere Möglichkeiten, E-Mail-Adressen zu erstellen. Alle Mailing-Komponenten verwenden ein EmailAddress Objekt. Sie können dieses Objekt überall dort als Argument verwenden, wo E-Mail-Adressen erwartet werden. Es gibt mehrere Möglichkeiten, ein solches Objekt zu erstellen.
// From a string
$address = EmailAddress::from('[email protected]');
$address = EmailAddress::from('<[email protected]>');
$address = EmailAddress::from('John Doe <[email protected]>');
// From email string and name
$address = EmailAddress::from('[email protected]', 'John Doe');
// From another object
$obj = new stdClass;
$obj->name = 'John Doe';
$obj->email = '[email protected]';
$address = EmailAddress::from($obj);
// From another EmailAddress
$address = EmailAddress::from($anotherEmailAddressObject);
Das bedeutet, dass Sie beim Erstellen von E-Mails diese Varianten verwenden können:
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
Die oben vorgestellten Konfigurationsobjekte können auch mithilfe von JSON-Strings, Objekten oder assoziativen Arrays erstellt werden. Die folgenden Snippets beschreiben die JSON-Objekte in Kurznotation.
SmtpConfig:
-----------
{
"host": "www.example.com",
"port": 587,
"debugLevel": 0,
"auth": true,
"secureOption": "starttls",
"charset": "utf8",
"credentials": {
"user": "username",
"pass": "password"
}
},
RerouteConfig:
--------------
{
"recipients": "[email protected]",
"subjectPrefix": "[Rerouted]"
},
BccConfig:
----------
{
"recipients": "[email protected]"
},
EmailConfig:
------------
{
"timezone": "Europe/Berlin",
"mailMode": "default",
"smtpConfig": {... see above ...},
"rerouteConfig": {... see above ...},
"bccConfig": {... see above ...},
"debugAddress": "[email protected]",
"defaultSender": "[email protected]",
"subjectPrefix": "[PHPUnitTest] "
}
Jede der Konfigurationsklassen stellt eine statische from() Methode bereit, die diese Typen als Argument verwendet und das Konfigurationsobjekt selbst zurückgibt:
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
Es ist möglich, ein Array von Email Objekten an die Funktionen send() und queue() zu übergeben. Allerdings sollten Sie sich insbesondere beim sofortigen Versenden von E-Mails darüber im Klaren sein, dass dies einige Zeit in Anspruch nehmen kann. Eine bessere Strategie besteht darin, Massenmailings in die Warteschlange zu stellen.
Die meisten PHPUnit-Tests werden nicht ausgeführt, wenn kein SMTP-Server oder keine Datenbank verfügbar ist. Die Komponententests prüfen die Umgebungsvariablen EMAIL_TEST_SMTP und EMAIL_DATABASE . Es gibt ein Bash-Skript, set-test-env.sh , das diese Variablen für Sie erstellt. Kopieren Sie es beispielsweise nach set-local-test-env.sh und befolgen Sie die Anweisungen in der Datei.
Melden Sie einen Fehler, fordern Sie eine Verbesserung oder einen Pull-Request im GitHub Issue Tracker an.
