===== Dokument via E-Mail in PHP versenden =====



Dieser Tip ist nicht als Ergänzung sondern als **Ersatz** zu den alten Tips zum Versenden eines Dokuments via E-Mail zu verstehen. Grund dafür ist, dass der Einsatz von Perl zur Programmierung von Skripten für (p2f)-Gateways nicht mehr empfehlenswert ist, weil sich einerseits die Lizenzbedingungen dahingehende verändert haben, dass kommerzieller Einsatz kostenpflichtig ist, und andererseits inzwischen immer weniger Entwickler mit Kenntnissen zu %%Perl%% verfügbar sind.

Deshalb wird in diesem Tip das alte Thema jetzt mit der Skriptsprache PHP realisiert.

Da PHP Objekte unterstützt, wurden von uns spezielle Klassen für den Einsatz zusammen mit (p2f) programmiert. Diese erleichtern das Programmieren erheblich, weil sie für häufig wiederkehrende Aufgaben bereits vorgefertigte Lösungen anbieten.

Für das Senden von E-Mails werden zwei **Klassen** benutzt. Zum einen ist das die Klasse [[print2forms:tips:tip96|control-class.php]], die die Analyse von Kontrolldateien unterstützt, und zum anderen ist das die Klasse [[print2forms:tips:tip95|email-class.php]], die - nomen est omen - die Ver(-)bindung zu einem E-Mail-Server herstellt. Zum genauen Verständins dieses Tips ist die Kenntnis dieser beiden Klassen notwendig.
\\
\\
==== Quellcode ====

Das Skript zum Erzeugen und Versenden von E-Mails muss drei Aufgaben erledigen:

  - Auslesen der Kontrolldatei, um Informationen zur Erzeugung des Inhalts der E-Mail zu erhalten - z.B. den Namen des Adressaten oder die Rechnungsnummer. Idealerweise ist auch die E-Mail-Adresse des Adressaten in der Kontroldatei zu finden, falls nicht, muss sie eventuell aus anderen Quellen, wie z.B. aus einer Datenbank, ermittelt werden.\\ \\ 
  - Konvertierung der Druckausgabe (die PCL-Datei) in eine PDF-Datei.\\ \\ 
  - Erzeugung des E-Mail-Textes, Einbindung der %%PDF%%-Datei und Versand der E-Mail.

Diese Aufgaben werden im nachfolgend abgebildeten Skript nacheinander erledigt.
\\
\\
Unter dem Link {{print2forms:tips:p2fMail.zip|p2fMail.zip}} steht ein Archiv mit einem vollständigen Projekt zum Austesten des Tips zur Verfügung. ((Ein Projekt für **Visual Studio Code** mit lokal installierten PHP. Inklusive der benötigten Klassen und Testdaten.\\ \\ ))

Interessiert nur das Skript alleine, sollte es vorzugsweise über diesen Link {{print2forms:tips:mail.php|mail.php}} geladen werden, weil beim Laden über den Reiter des Quellcodes die Unicode-BOM verlorengeht. ((Für die korrekte Funktion der Skripte ist es unumgänglich, dass Unicode zum Einsatz kommt. Die Kontrolldatei ist eine in UTF-8 kodierte Datei und somit müssen auch die zur Verarbeitung genutzten Skripte Unicode unterstützen. Ansonsten gibt es erhebliche Probleme mit länderspezifischen Zeichen. Die regulären Ausdrücke im Skript //mail.php// müssen aber ohne 'u' angegeben werden, weil dies in der Methode //fetch// automatisch ergänzt wird! Für eigene reguläre Ausdrücke ist aber der Modifier 'u' am Ende der RegEx zwingend!\\ \\ ))
\\
\\
<code php [enable_line_numbers="true"] mail.php>
<?php
/* E-Mail sending example - call: "C:\php\php.exe" "%1/mail.php" "%1" "%2" %4 */

require "control-class.php";
require "email-class.php";

chdir (dirname(__FILE__));            /* active directory is script directory */

if ($argc < 4)
  control::error ("Invalid number of arguments $argc", 1);

$spool    = $argv [2];                            /* path to spooled document */
$document = $argv [3];                  /* name of document without extension */

$vars = array ();

$p2f = new control("Europe/Berlin", "$spool\\$document.ctl");

$p2f->fetch ("01012D0846", $vars, "(\d+)", "rechnum");
$p2f->fetch ("0102410846", $vars, "(\d+)", "kndnum");
$p2f->fetch ("01036C00C6", $vars, "(.*)", "kndname");
$p2f->fetch ("01050A0229", $vars, "(.*)", "kndmail");
$p2f->fetch ("0102860846", $vars, ".+ (\d+)", "auftrnum");
$p2f->fetch ("0101720846", $vars, "(\d\d\.\d\d\.\d{4})", "rechdatum");

/* PDF file creation with supplied meta data */

$pdf = $p2f->createpdf ("$spool\\$document.pcl",
                        "Lieferant GmbH",
                        "Rechnung {$vars ["rechnum"]}",
                        "{$vars ["rechnum"]}; {$vars ["rechdatum"]}; {$vars ["kndnum"]}");

if ($pdf != "")                                    /* pdf creation successful */
  {
    $data = array
      (
        "from"     => "info@lieferant-gmbh.local",
        "fromname" => "Buchhaltung Lieferant GmbH",
        "to"       => $vars ["kndmail"]
        "toname"   => $vars ["kndname"],
    //  "cc"       => "",
    //  "ccname"   => "",
        "file"     => $pdf,
        "filename" => "Rechnung {$vars ["rechnum"]}.pdf",
        "subject"  => "Lieferant GmbH - Rechnung {$vars ["rechnum"]}",
        "body"     =>

        $p2f->substitute ("Sehr geehrte Damen und Herren,<br/><br/>" .
                          "vielen Dank für Ihren Auftrag @auftrnum@.<br/><br/>" .
                          "Mit dieser Mail erhalten Sie dazu unsere Rechnung @rechnum@<br/>" .
                          "mit Datum vom @rechdatum@ im Format PDF/A.<br/><br/>" .
                          "Mit freundlichen Grüßen<br/>" .
                          "Ihre Lieferant GmbH<br/><br/><br/>" .
                          "Lieferant GmbH<br/>" .
                          "Lieferweg 21<br/>" .
                          "80345 Musterstadt<br/><br/>" .
                          "Tel.: +49 1234 1234-0<br/>" .
                          "Fax:  +49 1234 1234-123<br/><br/>" .
                          "Mail: info@lieferant-gmbh.local<br/><br/>" .
                          "Geschäftsführer: A. Mustermann<br/>" .
                          "Registergericht Musterstadt: 5 HRB 12345<br/>" .
                          "USt-IdNr.: DE123456789<br/>", $vars)
      );

    $em = new email ("server", 465, "user", "password");

    if ($em->sendmail ($data, $message) == 0)
      $p2f->error ("Sending e-mail failed '$message'", 0);
  }
else
  $p2f->error ("No document available for e-mail", 0);

if ($p2f->errorsfound () != 0)
  exit (-1);
?>
</code>
\\
Das Skript startet als erstes mit der Einbindung der beiden notwendigen Klassen in den Zeilen 4 und 5. Danach wird das aktuelle Arbeitsverzeichnis auf das Skriptverzeichnis gesetzt (Zeile 7), um so bei weiteren Dateinamen keine langen Pfade mit angeben zu müssen.

Nach der Prüfung der Argumente (Zeilen 9 bis 13) wird ein zunächst leeres Array zum Aufsammeln der für die E-Mail wichtigen Informationen angelegt (Zeile 15). Dieses Array wird in den Folgezeilen nach und nach mit Texten aus der Kontrolldatei gefüllt. Die regulären Ausdrücke geben für einzelne Daten schon feste Formate vor, so z.B. beim Rechnungsdatum (Zeile 24).

Mit Zeile 28 wird dann die Erzeugung der %%PDF%%-Datei initiiert. Neben dem Namen der %%PCL%%-Datei wird der Firmenname, eine Dokumentbeschreibung und eine Reihe von Schlüsselworten mitgegeben. Diese werden als Meta-Daten in die %%PDF%%-Datei mit eingebaut und erleichtern so die Nachverarbeitung der Datei beim Empfänger.

<columns 100% left 30%  ->
Ist die %%PDF%%-Datei erfolgreich erzeugt worden (Zeile 33), wird nun die E-Mail erzeugt.

Dazu wird die in der Klasse //email-class.php// vorgegebene Schnittstelle erzeugt (Zeilen 35 bis 63). Im personalisierten Text für die E-Mail werden ebenfalls Texte aus der Kontrolldatei mit eingesetzt. Die E-Mail-Adresse und der Klarnamen des Empfängers sind ebenfalls aus der Kontrolldatei extrahierten Texte.

Nachdem die Schnittstelle vollständig ist, kann der Versand der E-Mail initiiert werden (Zeile 65). Dazu sind die Kontaktdaten des Mail-Servers notwendig. ((Falls dies nicht in jedem Skript extra konfiguriert werden soll, weil dies den Wartungsaufwand im Falle von Änderungen am Mail-System erhöht, kann eine Vorbelegung der Kontaktdaten des Mail-Servers bereits in der Klasse //email-class.php// mittels initialisierter Parameter erfolgen. Im aufrufenden Skript müssen dann keine Parameter mehr angegeben werden.\\ \\ ))

Der eigentliche Versand erfolgt in Zeile 67. Im Falle eines Fehlschlags wird eine Meldung mit der Fehlernachricht des Mail-Servers ausgegeben. 

Die Zeilen 73 und 74 sorgen dafür, dass das Skript mit einem Fehlercode terminiert. Dieser Fehlercode wird dann auch in die Ablaufverfolgung des aufrufenden (p2f)-Gateways eingetragen.
<newcolumn>
{{ print2forms:tips:0093-1.png|Die Meta-Daten der vom Skript erzeugte PDF-Datei}}
</columns>
\\
Die erzeugte E-Mail im HTML-Format und als reiner Text:
<columns 100% left 50% rigth ->
{{print2forms:tips:0093-2.png?400 |Die E-Mail mit Anhang im HTML-Format}}
<newcolumn>
{{ print2forms:tips:0093-3.png?400|Die E-Mail mit Anhang im Text-Format}}
</columns>
\\
\\
==== Hinweise ====

  * Soll das Projekt **p2fMail** in Betrieb genommen werden, kann es sein, dass in der Datei //launch.json// der Pfad auf die %%PHP%%-Installation an die lokalen Gegebenheiten angepasst werden muss. Das Projekt selbst sollte im Skriptver(-)zeichnis von (p2f) abgelegt werden. Was auch klar sein sollte: die E-Mail-Adressen und der Zugriff auf den Mail-Server in //mail.php// müssen ebenfalls angepasst werden. In der Datei //launch.json// ist das Spoolverzeichnis so gesetzt, dass die beiden Dateien aus dem Unterverzeichnis //test// verwendet werden!

  * Das Projekt **p2fMail** kann und sollte dann, wie in den Tips [[print2forms:tips:tip70|Visual Studio Code für PHP installieren]], [[print2forms:tips:tip71|Test von PHP Skripten]] und [[print2forms:tips:tip72|PHP-Skript ohne Gateway testen]] beschrieben, angepasst und getestet werden. 
 
  * Aus lizenzrechtlichen Gründen dürfen die Programme [[https://www.ghostscript.com/releases/gpcldnld.html|GhostPCL]] und [[https://www.ghostscript.com/releases/gsdnld.html|GhostScript]] der Firma Artifex nicht mit (p2f) zusammen ausgeliefert werden. Sie sind daher nicht Bestandteil des Projekts //p2fMail//.\\ \\ Nachdem die Programme von den hier angegebenen Web-Adressen geladen wurden, müssen für GhostPCL die beiden Dateien //gpcl6win64.exe// und //gpcl6win64.dll// (für 64-Bit Systeme, ansonsten //gpcl6win32.exe// und //gpcl6win32.dll// für 32-Bit Systeme) in den Ordner //converter// kopiert werden. Für GhostScript müssen die beiden Dateien //gswin64.exe// und //gsdll64.dll// (für 64-Bit Systeme, ansonsten //gswin32.exe// und //gsdll32.dll// für 32-Bit Systeme) kopiert werden.
\\
\\