SideBarMenu

StudipMail

Mit Stud.IP Version 1.10 wurde die neue Klasse StudipMail eingeführt. Diese Klasse bietet Möglichkeiten eine Email zu erzeugen und zu versenden. Der Versand der Nachricht wird nicht direkt von der Klasse vorgenommen, sondern von einer Instanz einer weiteren Klasse für den Emailtransport. Die dazu benutzen Klassen befinden sich in vendor/email_message, hier gibt es verschiedene Möglichkeiten für den Transport z.B. über die php Funktion Mail oder über smtp.

schnelles Beispiel

  1. $mail = new StudipMail();
  2. $mail->addRecipient('suchi@data-quest.de', 'Stefan Suchi')
  3.      ->addRecipient('elmar.ludwig@uos.de', 'Elmar Ludwig', 'Cc')
  4.      ->setSubject('Test der Mail Klasse')
  5.      ->addStudipAttachment($dokument_id)
  6.      ->setBodyText("Hallo,\nBlablubb")
  7.      ->send();

Funktionsweise

Mail Transport

Welcher Transport für die Mail benutzt wird, kann ich der config/config_local.inc.php bei den Maileinstellungen mit $MAIL_TRANSPORT konfiguriert werden. Hier stehen zur Auswahl:

  • smtp direkte smtp Verbindung zu $MAIL_HOST_NAME
  • php php mail() Funktion wird genutzt
  • sendmail direktes Aufrufen des lokalen sendmail skriptes
  • qmail direktes Aufrufen des lokalen qmail skriptes
  • debug mails werden nicht verschickt sondern in eine Datei in $TMP_PATH geschrieben
  • blackhole mails werden nicht verschickt sondern einfach verworfen

Aufgrund dieser Einstellung wird automatisch in lib/phplib_local.inc.php eine Instanz der entsprechenden Transporterklasse erzeugt und mit StudipMail::setDefaultTransporter($mail_transporter) als Standardweg zum verschicken hinterlegt.

Es ist aber möglich dieses Objekt auszutauschen, entweder über den obigen Aufruf von StudipMail::setDefaultTransporter(), oder aber beim Aufruf von StudipMail::send(), da die send Methode als optionalen Parameter ein von email_message_class abgeleitetets Objekt akzeptiert.

Damit ist es auch möglich den automatischen Versand von Mails temporär zu verhindern, wie es z.B. die UserManagement Klasse bei Änderungen eines Nutzers macht:

  1. class null_message_class extends email_message_class
  2. {
  3.     function SendMail($to,$subject,$body,$headers,$return_path) {
  4.     }
  5. }
  6. $umanager = new UserManagement();
  7. $null_mailer = new null_message_class();
  8. $default_mailer = StudipMail::getDefaultTransporter();
  9. StudipMail::setDefaultTransporter($null_mailer);
  10. $umanager->createNewUser($data));
  11. StudipMail::setDefaultTransporter($default_mailer);

In der Version 2.0 ist die obige null_message_class nicht mehr nötig, für diesen Zeck kann man eine Instanz der Klasse blackhole_message_class heranziehen:

  1. require_once 'vendor/email_message/blackhole_message.php';
  2. $umanager = new UserManagement();
  3. $suck_it_down = new blackhole_message_class();
  4. $default_mailer = StudipMail::getDefaultTransporter();
  5. StudipMail::setDefaultTransporter($suck_it_down);
  6. $umanager->createNewUser($data));
  7. StudipMail::setDefaultTransporter($default_mailer);

Mails erstellen

Um eine Mail zu erstellen erzeugt man ein neues StudipMail Objekt und füllt es über die diversen add und set Methoden mit Inhalt. Alle add und set Methoden liefern immer das aktuelle Objekt zurück, damit man mehrere Aufrufe hitereinandersetzen kann ("fluent interface"). Die wesentlichen Methoden sind:

  • setSenderEmail($mail)

setzt die Mailadresse des Absenders. Die Absendeadresse wird im Konsruktor auf $MAIL_ENV_FROM vorbelegt.

  • setSenderName($name)

setzt den Namen des Absenders, wird auf $MAIL_FROM vorbelegt

  • setReplyToEmail($mail)

setzt die Mailadresse für das reply-to, wird mit $MAIL_ABUSE vorbelegt.

  • setSubject($subject)

setzt den Titel der Mail

  • addRecipient($mail, $name = '', $type = 'To')

fügt einen Empfänger hinzu. Der erste Parameter muss die Mailadresse enthalten, der nächste enthält optional den Namen. Mit dem dritten Parameter kann man einstellen ob es sich um einen Standardempfänger ('To'), einen Kopieempfänger ('Cc') oder einen Blindkopieempfänger ('Bcc') handelt.

  • addDataAttachment($data, $name, $type = 'automatic/name', $disposition = 'attachment')

fügt einen Datenanhang der Mail hinzu. Über den $type Parameter sollte man eine korrekten mime-type mit angeben-

  • addFileAttachment($file_name, $name = '', $type = 'automatic/name', $disposition = 'attachment')

fügt einen Dateianhang der Mail hinzu. Über den $type Parameter kann man einen korrekten mime-type mit angeben, ansonsten wird versucht auf Basis des Dateinamens zu entscheiden. $file_name muss den kompletten Pfad zur Datei enthalten.

  • addStudipAttachment($dokument_id)

fügt einen Dateianhang der Mail hinzu, es muss nur die Stud.IP Dokumenten ID übergeben werden, die anderen Parameter werden dann direkt aus der Datenbank befüllt.

  • setBodyText($body)

setzt den Textinhalt der Mail

  • setBodyHtml($body)

setzt den HTML Inhalt der Mail. Es wird dann immer eine multipart Mail erzeugt, wenn der Textinhalt fehlt wird dafür ein Hilfstext eingefügt.

  • function send(email_message_class $transporter = null)

versendet die Mail, mit dem optionalem Parameter kann das transport Objekt vorgegeben werden. Die Methode liefert true zurück wenn die Mail verschickt werden konnte.

Letzte Änderung am 05.08.2010 19:04 Uhr von anoack.