===== email-class.php =====

Sehr oft müssen Skripte, die durch ein (p2f)-Gateway aufgerufen werden, Informationen via E-Mail an Kunden oder Lieferanten automatisiert weiterreichen. Dabei steht immer auch die Anbindung eines %%PHP%%-Skriptes an einen E-Mail-Server in Frage.

Um das nicht in jedem Skript neu ausformulieren zu müssen, wird hier eine %%PHP%%-Klasse mit dem Namen **email-class** vorgestellt, die den Aufwand zum Absenden einer E-Mail vereinfachen soll.
\\
\\
==== Quellcode ====

Die im Quellcode nachfolgend dargestellte Klasse übernimmt eigentlich nur die Aufgaben, den E-Mail-Server auszuwählen und dann die gewünschte E-Mail abzusenden. Dabei kann die Mail zusätzlich an eine weitere Adresse (CC) gesandt werden. Weil eine E-Mail in aller Regel auch ein Dokument als Anhang benötigt, ist das ebenfalls vorgesehen.

Das Skript sollte vorzugsweise über diesen Link {{print2forms:tips:email-class.php|email-class.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.\\ \\ ))
\\
\\
<code php email-class.php>
<?php

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;
use PHPMailer\PHPMailer\SMTP;

require "C:/php8/PHPMailer/src/Exception.php";
require "C:/php8/PHPMailer/src/PHPMailer.php";
require "C:/php8/PHPMailer/src/SMTP.php";

class email
  {
    private $server = "";
    private $port = 0;
    private $username = "";
    private $password = "";

/*----------------------------------------------------------------------------*/

    public function __construct ($server ="server.de",
                                 $port = 465,
                                 $username = "user",
                                 $password = "passwart")
      {
        $this->server = $server;
        $this->port = $port;
        $this->username = $username;
        $this->password = $password;
      }

/*----------------------------------------------------------------------------*/

    function sendMail ($data, & $msg)
      {
        $mail = new PHPMailer ();

        $mail->isSMTP ();
        //$mail->SMTPDebug = SMTP::DEBUG_LOWLEVEL;

        $mail->Host       = $this->server;
        $mail->Port       = $this->port;
        $mail->SMTPAuth   = true;
        $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
        $mail->Username   = $this->username;
        $mail->Password   = $this->password;
        $mail->CharSet    = "UTF-8";

        $mail->isHTML (true);
        $mail->setFrom ($data ["from"], $data ["fromname"]);
        $mail->addAddress ($data ["to"], $data ["toname"]);

        if (array_key_exists ("cc", $data))                 /* cc is optional */
          $mail->addCC ($data ["cc"], $data ["ccname"]);

        $mail->addAttachment ($data ["file"], $data ["filename"]);
        $mail->Subject = $data ["subject"];
        $mail->Body = $data ["body"];
        $mail->AltBody = strip_tags (str_replace ("<br/>", "\n", $mail->Body));

        if (! $mail->send ())
          {
            $msg = trim ($mail->ErrorInfo);
            $mail = null;
            return 0;
          }

        $mail = null;
        $msg = "";
        return 1;
      }
  }
?>
</code>
\\
==== Konstruktor ====

Der Konstruktor der Klasse benötigt als Parameter die Daten für den E-Mail-Server. Das sind dessen Adresse, die zu benutzende Port-Nummer, sowie den Anmeldenamen und das Passwort.

Die Parameter sind mit Standardwerten angelegt. Damit steht es dem Nutzer frei, ob er in jedem seiner %%PHP%%-Skripte die Anmeldedaten als Parameter mit übergibt, oder ob er das einmal durch eine Modifikation des Konstruktors erledigt. In diesem zweiten Fall sind die eigentlichen Skripte unabhängig von den Anmeldedaten, was im Sinne der Wartbarkeit zu bevorzugen ist. ((Bei der Verbindung zum E-Mail-Server wird unterstellt, dass dies eine verschlüsselte Verbindung ist. Sollte das wieder Erwarten im Einzelfall nicht zutreffen, sind gegebenenfalls weitere Modifkationen innerhalb der Klasse notwendig.\\ \\ ))
<code php>
    $em = new email ("server", 587, "user", "password");
</code>
<code php>
    $em = new email ();
</code>
\\
==== sendMail ====

Die Methode benötigt zwei Parameter. Zum einen ist das ein Array mit den Daten für die E-Mail, und zum zweiten die Adresse einer Zeichenkette, in der im Falle eines Fehlers die Meldung des Mail-Servers landet.

Das Array liefert über die entsprechenden Schlüssel die notwendigen Daten:

^ Schlüssel ^ Inhalt ^
| from | E-Mail-Adresse des Absenders der E-Mail | 
| fromname | Klartextname des Absenders der E-Mail | 
| to | E-Mail-Adresse des Empfängers der E-Mail |
| toname | Klartextname des Empfängers der E-Mail |
| cc | E-Mail-Adresse des Kopie-Empfängers der E-Mail (optional) |
| ccname | Klartextname des Kopie-Empfängers der E-Mail (optional) |
| file | Pfad und Name der Datei, die als Anhang beigefügt werden soll |
| filename | Name der Datei, wie er in der E-Mail als Anhang erscheinen soll |
| subject | Betreffzeile der E-Mail |
| body | Inhalt der E-Mail als HTML-Zeichenkette. Diese wird als  **%%HTML%%**-Teil der E-Mail genutzt. Als reiner **Text**-Teil der E-Mail wird automatisch eine Zeichenkette erzeugt, bei der alle '<br/>'-Tags gegen Zeilenvorschübe ersetzt und alle anderen %%HTML-%%Tags entfernt sind. |
\\
Der Rückkehrwert der Methode ist Eins wenn das Versenden erfolgreich war. Die übergebenen Zeichenkette ist dann leer. Im Fehlerfall wird eine Null zurückgegeben und die übergebene Zeichenkette enthält den (technischen, meist englischen) Fehlertext des E-Mail-Servers.

Ein Beispiel für die Erzeugung einer E-Mail:
\\
<code php>
$data = array
  (
    "from"     => "info@lieferant-gmbh.local",
    "fromname" => "Buchhaltung Lieferant GmbH",
    "to"       => $vars ["CustomerMail"],
    "toname"   => $vars ["CustomerName"],
    "file"     => $pdf,
    "filename" => "Rechnung {$vars ["InvoiceNo"]}.pdf",
    "subject"  => "Lieferant GmbH - Rechnung {$vars ["InvoiceNo"]}",
    "body"     =>

    $p2f->substitute ("Sehr geehrte Damen und Herren,<br/><br/>" .
                      "vielen Dank für Ihren Auftrag @OrderNo@.<br/><br/>" .
                      "Mit dieser Mail erhalten Sie dazu unsere Rechnung @InvoiceNo@<br/>" .
                      "mit Datum vom @InvoiceDate@ 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 ();

if ($em->sendMail ($data, $message) == 0)
  $p2f->error ("Sending e-mail failed '$message'");  
</code>
\\
==== Hinweise ====
  * Die Methode //sendMail// kann mehrfach aufgerufen werden, ohne jedes mal die Klasse //email-class// neu instanziieren zu müssen. Das ist möglich, weil innerhalb der Klasse das Objekt für den PHPMAILER jedes mal neu instanziiert und dann wieder durch expliziten Aufruf des Destruktors gelöscht wird. ((Dadurch kann z.B. im Falle, dass die E-Mail nicht zustellbar ist, eine Fehler-E-Mail an einen Help-Desk oder an den Absender gehen, um über das Problem zu informieren.\\ \\ ))

  * Innerhalb der Klasse werden die einzelnen %%PHP%%-Erweiterungen des Moduls **PHPMAILER** direkt eingebunden, so wie das bei einer Installation via **GitHub** notwendig wird. Dazu muss gegebenenfalls der Pfad auf die %%PHP%%-Installation angepasst werden. Wenn die Installation von PHPMAILER via **Composer** erfolgte, sind die drei Zeilen gegen ''%%require_once "vendor/autoload.php";%%'' zu ersetzen.

  * Das ist hier nur ein Grundgerüst, dass in einigen Fällen nicht ausreichen mag. Wenn mehrere Empfänger, mehrere Anhänge, oder ähnliches benötigt werden, muss die Klasse entsprechend angepasst und erweitert werden. Zum Beispiel durch die Nutzung von Arrays für Empfänger oder Anhänge.

  * Auch wenn die gestalterischen Ansprüche an die HTML-Version der Mail höher sind, zum Beispiel weil auch das Firmenlogo angezeigt und jedes mal mit eingebunden übertragen werden soll, sind Anpassungen notwendig. Sprechen Sie uns in solchen Fällen an.
  
  * Auch die automatische Reduktion des %%HTML%%-Teils auf einen Text-Teil hat irgendwann ihre Grenzen. Eventuell müssen dann beide Teile getrennt voneinander formuliert und einzeln (Body und AltBody) eingebunden werden. 
\\