The symfony Cookbook

Überblick

Das Versenden von Mails ist eine Standardaufgabe vor der jeder Webentwickler einmal steht. Dank symfony 1.1 und Swift Mailer ist dies so einfach wie nie zuvor.

Swift Mailer ist eine durchdachte Klassenbibliothek welche 120% aller Mailbedürfnisse abdeckt.

Sie ist als getaggte version aus dem SVN Repository verfügbar, was verhindert, daß Projekte durch Änderungen im Swift Mailer Projekt beinflusst werdem. Die benutzte Version kann dadurch auch sehr leicht gewechselt werden.

Symfony's Art eMails zu verschicken ist recht einfach. Man erstellt ein Partial oder eine Komponente, welche dann als eMail Inhalt gerendert wird. Swift verschickt das Ergebnis dann auf die gewünschte und flexibel konfigurierbare Art.

Installation

Wenn das Projekt bereits SVN benutzt kann Swift Mailer ganz einfach über das svn:externals Property eingebunden werden:

$ cd /path/to/symfony/project
$ mkdir -p lib/vendor
$ svn propedit svn:externals .

Folgende Zeile muss dafür eingefügt werden:

swift http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/tags/php5/3.3.3/lib/

Wenn das Projekt kein SVN benutzt kann anstelle dessen ein Checkout des gewüschten Swift Mailer Versionstags benutzt werden:

$ cd /path/to/symfony/project
$ mkdir -p lib/vendor
$ svn checkout http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/tags/php5/3.3.3/lib/ swift

Nach dem Löschen des Caches mittels symfony cc findet das symfony Autoloading die neuen Klassen und Swift Mailer ist einsatzbereit.

Konfiguration

Es gibt keine Swift Mailer spezifische Konfigurationsdateien. Etwaige Konfiguration findet im Code statt.

Allerdings sollte man, um das Projekt flexibel zu halten, die app.yml Konfigurationsdatei benutzen um projektbezogene eMailadressen und Server zu definieren. Dadurch können in verschiedenen Umgebungen andere Versender- oder Empfängeradressen genutzt werden. Auch ist es sehr leicht bei Änderungen diese an einer Stelle zu ändern anstelle sie im kompletten Projekt suchen zu müssen (ganz getreu dem DRY Prinzip).

eMail Inhalt erstellen

Seit symfony 1.1 RC2, können Partials und Komponenten ganz einfach von einer Action aus gerendert und als Text, zum Beispiel für die eMail, verwendet werden:

$mailBody = $this->getPartial('mailBody', array('name' => 'John Doe'));
 

oder:

$mailBody = $this->getComponent('mail', 'mailBody', array('name' => 'John Doe'));
 

Eine HTML eMail versenden

Danach wird die soeben gerenderte Mail mit Swift versandt:

try
{
  // Erzeuge ein neues Swift (Verbindung) und Swift Message (eMail) Objekt
  $mailer = new Swift(new Swift_Connection_NativeMail());
  $message = new Swift_Message('Betreff als Text', $mailBody, 'text/html');
 
  // verschicken
  $mailer->send($message, $mailTo, $mailFrom);
  $mailer->disconnect();
}
catch (Exception $e)
{
  $mailer->disconnect();
 
  // weitere Fehlerbehandlung
}
 

Eine multipart eMail verschicken

Manche eMail Programme oder Anwender mögen keine HTML eMails, insofern ist es eine gute Idee eine eMail auch als "plain text" mitzuschicken. Die Kombination von HTML und Text bezeichnet man auch als Multipart.

try
{
  // Erzeuge ein neues Swift (Verbindung) und Swift Message (eMail) Objekt
  $mailer = new Swift(new Swift_Connection_NativeMail());
  $message = new Swift_Message('Betreff als Text');
 
  // Erstelle die Nachrichtenteile
  $mailContext = array('name' => 'John Doe');
  $message->attach(new Swift_Message_Part($this->getPartial('mail/mailHtmlBody', $mailContext), 'text/html'));
  $message->attach(new Swift_Message_Part($this->getPartial('mail/mailTextBody', $mailContext), 'text/plain'));
 
  // Verschicken
  $mailer->send($message, $mailTo, $mailFrom);
  $mailer->disconnect();
}
catch (Exception $e)
{
  $mailer->disconnect();
 
  // weitere Fehlerbehandlung
}
 

Verschiedene Verbindungseinstellungen benutzen

Bei der Erstellung ders Swift Objektes können verschiedene Swift_Connection Objekte übergeben werden welche zur Konfiguration des Mail Servers dienen.

• Swift_Connection_NativeMail benutzt die gleiche Verbindung wie sie auch die native PHP Funktion mail() nutzt.

• Swift_Connection_SMTP verschickt Mails über einen SMTP Server. Der Konstruktor akzeptiert drei Parameter welche allerdings alle optional sind:

  public function __construct($server="localhost", $port=null, $encryption=null)
   

  Weitere Details zur Benutzung dieser Verbindung folgen später anhand eines Beispiels zum Versenden von eMails mittels einen gesicherten Mailservers: gmail mit SMTP.

• Swift_Connection_Sendmail benutzt das externe Programm sendmail zum Versand der eMail. Der Pfad zu sendmail kann im Konstruktor angegeben werden.

• Swift_Connection_Multi ist ein Wrapper der es erlaubt mehrere Verbindungen zu benutzen. Dadurch bietet es Redundanz und Absicherung falls ein SMTP Server zum Zeitpunkt der Anfrage nicht verfügbar ist. Der Konstruktor erwartet ein Array von Swift_Connection Objektinstanzen und kann sogar weitere Swift_Connection_Multi Instanzen verarbeiten (auch wenn dies ein eher abstraktes Szenario ist).

• Swift_Connection_Rotator ähnelt der Swift_Connection_Multi erlaubt jedoch mehr Funktionalität. So wird zum Beispiel die Last auf die verfügbaren SMTP Server verteilt. Erläuterungen zu dieser Funktionalität würden den Umfang dieser Anleitung überschreiten und sind in der Swift Mailer Dokumentation beschrieben.

Google Mail SMTP Server benutzen

Einen gmail Zugang zum Versand von eMails zu benutzen bietet eine Reihe von Vorteilen?

• Es muss kein SMTP Server aufgesetzt und gewartet werden
• Da die Google Server von vielen Spam Filtern akzeptiert werden ist es wahrscheinlicher, daß eMails nicht als SPAM erkannt werden
• Gesendete emails erscheinen automatisch in Sent items des Google Mail Zuganges und erleichtern so das Auffinden von Fehlern

Allerdings existieren folgende Beschränkungen

• Ein gültiger gmail Zugang wird benötigt
• SMTP über SSL Abwicklung ist langsamer als ohne SSL
• eMails können nicht von beliebigen Absendeadressen gesendet werden. Allerdings können neue Absender zu dem Google Zugang hinzugefügt werden

Bei Benutzung von gmail muss das Swift Objekt wie folgt konfiguiert werden:

$connection = new Swift_Connection_SMTP('smtp.gmail.com', 465, Swift_Connection_SMTP::ENC_SSL);
$connection->setUsername('romain@gmail.com');
$connection->setPassword('SuperSecurePassword');
 
$mailer = new Swift($connection);
 

Bilder einfügen

Um Bilder in eMails einzufügen müssen eMail relative URLS von den einzufügenden Objekten erstellt werden bevor der Inhalt gerendert werden kann. Das folgende Beispiel illustriert dies:

// Erzeuge ein neues Swift (Verbindung) und Swift Message (eMail) Objekt
$mailer = new Swift(new Swift_Connection_NativeMail());
$message = new Swift_Message('Test mail subject');
 
// Eingebettete Bilder
$images = array();
$images['symfony'] = new Swift_Message_Image(new Swift_File(sfConfig::get('sf_web_dir').'/images/symfony.gif'));
$images['swift']   = new Swift_Message_Image(new Swift_File(sfConfig::get('sf_web_dir').'/images/swift.jpg'));
 
$imageReferences = array();
foreach ($images as $name => $image)
{
  $imageReferences[$name] = $message->attach($image);
}
 
// Erstelle die Nachrichtenteile
$mailContext = array('name' => 'John Doe', 'images' => $imageReferences);
$message->attach(new Swift_Message_Part($this->getPartial('mail/mailHtmlBody', $mailContext), 'text/html'));
$message->attach(new Swift_Message_Part($this->getPartial('mail/mailTextBody', $mailContext), 'text/plain'));
 
// Versenden
$mailer->send($message, $mailTo, $mailFrom);
$mailer->disconnect();
 

In dem Partial / in der Komponente können die eingebetteten Bilder ganz leicht mittels folgendem Codes angezeigt werden:

<img src="<?php echo $images['symfony']; ?>" alt="Symfony Project" />
<img src="<?php echo $images['swift']; ?>" alt="Swift Mailer" />

Dateianhänge

Dateien an eMails anzuhängen ist ebenfalls sehr einfach:

$message->attach(new Swift_Message_Attachment(new Swift_File($file), $filename, $mime_type));
 

Empfängerlisten

Oft soll eine eMail an mehrere Empfänger gehen. Dabei wird zwischen Empfängern (to), Kopien (cc) und Blindkopien (bcc), welche für andere Empfänger nicht sichtbar sind, unterschieden. Dies kann mit der Swift_RecipientList konfiguriert werden.

$recipients = new Swift_RecipientList();
$recipients->addTo($to);
$recipients->addCc($cc);
$recipients->addBcc($bcc);
 

Allerdings muss darauf geachtet werden die $recipients Liste mittels ->flush() zu leeren wenn in einer Schleife e-Mails verschickt werden sollen, da andernfalls die vorherigen Empfänger noch in der Liste enthalten sind und so doppelte oder falsch adressiere eMails versandt werden.

eMails aus einem Task verschicken

Aus Tasks können eMails genau wie aus Actions versandt werden. Allerdings kann das rendering der Action nicht mehr direkt benutzt werden.

Anstatt der sfAction::getPartial() und sfAction::getComponent() Methoden müssen die get_partial() und get_component() Funktionen aus dem PartialHelper verwendet werden.

Weitere Dokumentation

Auf der SwiftMailer Webseite finden sich eine gute Dokumentation und verständliche Tutorials.

Ausserdem ist die vollständige API Referenz verfügbar.