(1) Informationen zur Nutzung der Klasse Mailer

(1.1) Die Klasse Mailer stellt ein Formular zur Erfassung sämtlicher Angaben für den Nachrichten-Versand bereit. Es müssen darin ausgefüllt werden:
Absender, Empfänger (via Bcc adressiert), Betreff und Text.
Es können ebenfalls Kopie-Empfänger (via Cc adressiert) angegeben werden, und als Anhänge sind lokal gespeicherte Dateien auswählbar. Auch ist die Auswahl von (zuvor vom Nutzer bereits gespeicherter) Vorlagen möglich, um die Daten regelmäßig genutzter Nachrichten nicht jeweils neu erfassen zu müssen.

(1.2) Das Verarbeiten der Formular-Daten besteht je nach vorliegenden Daten in:

(1.3) Das Erfassungs-Formular wird durch Klick auf diese Buttons nur zeitweilig verlassen:

Durch Klick auf Neuer Anhang: [Durchsuchen...] öffnet sich ein zusätzliches Fenster für die Datei-Auswahl. Nach Auswahl einer oder mehrerer Dateien und Bestätigen mit [Öffnen] sind diese als Anhang markiert, werden aber erst durch [Hinzufügen] als Anhang beigefügt. Nach Ausführung diser Verarbeitung(en) wird das Formular mit allen bereits erfassten Daten erneut angezeigt.

(1.4) Versendet wird die Nachricht an die angegebenen Empfänger versteckt (Bcc; also ohne in der Mail oder im Mail-Kopf sichtbare Angabe deren Adressen) und mit offen erkennbaren Adressen (Cc) an die angegebenen Kopie-Empfänger sowie immer auch an den Absender selbst (offen mit To-Adressierung). Zusätzlich erhält der Absender einen Sende-Report, falls dies vom Schul-Admin konfiguriert ist: Parameter sendResult mit Wert '1' (Standard). Das Abbrechen der Nachrichten-Verarbeitung durch [Abbruch] muss in einer zusätzlichen Sicherheits-Abfrage bestätigt werden, ansonsten kehrt man zurück zum Erfassungs-Formular.

(1.5) Vor dem Senden der Nachricht werden Kopien der ggf. ausgewählten Anhang-Dateien auf den Server geladen. Nach dem Senden oder Abbruch werden diese sofort wieder vom Server gelöscht. Es ist also wichtig, das Mailer-Modul nur über die Buttons [Absenden] oder [Abbruch] zu verlassen, da ansonsten die Anhang-Datei-Kopien auf dem Server blieben, bis der Benutzer die nächste Nachricht mit Anhängen verschickt!

(2) Informationen zur Einbindung der Klasse Mailer in eigene Skripte

Der Mailer-Klassen-Konstruktor kann mit oder ohne Parameter aufgerufen werden.

(2.1) Aufruf des Konstruktors OHNE Parameter zum Versand ohne vorherige Formular-Anzeige:

(2.1.1) Zum sofortigen Versenden von Nachrichten wird der Mailer-Konstruktor ohne Parameter aufgerufen. Danach muss zum Versenden die Mailer-Methode send() mit Parametern aufgerufen werden. Danach kann mit Aufruf der Methode getErrors() überprüft werden, ob das gelieferte Array aus Strings Fehlermeldungen enthält oder das Senden erfolgreich war:

  
      $mailerO = new Mailer ();  // Aufruf ohne Parameter
      // Festlegen der Parameter-Werte:
      $parameters = Array(
        'from'        => 'vorname.nachname@firma.de',
        'bcc'         => 'vorname.nachname@firma.de, vor2.nach2@firma2.de', vor3.nach3@firma2.de'
        'subject'     => '[Der Betreff] der Nachricht',
        'text'        => 'Der Text der Nachricht'
        );
      $mailerO->send ($parameters);  // Methoden-Aufruf mit Parameter-Array
      // Überprüfung und ggf. Anzeige eingetretener Fehler:
      $tmpA = $mailerO->getErrors();
      echo '<p>'.(count($tmpA) > 0
          ? 'Es traten Fehler auf:<br />'.implode('<br />', $tmpA)
          : 'Versenden war erfolgreich'
          ).'</p>';
    
(2.1.2) Pflicht-Parameter für den Aufruf der Methode send() sind:
      from (Text, Adresse), 
      subject (Text, Betreff), 
      text (Text, Nachrichtentext)
    
(2.1.3) Mögliche weitere Parameter für den Aufruf der Methode send() sind:
      sender (Text, Adresse des Absenders, anders als from, wird für to und Reply-To genutzt)
      to (Text, eine Adresse), 
      bcc (Text, komma-getrennte Empfänger-Adressen), 
      cc (Text, komma-getrennte Kopie-Empfänger-Adressen),
      language (Text, de oder en), 
      noInfo (Text, 1 = keine Ergänzung des Nachrichten-Textes: 
      oben um Absender-Adresse und unten um Prog-Info)
    
(2.1.4) Um die DKIM-Zertifizierung beim Versenden sicherzustellen, müssen der Server der Absende-Adresse und der hostende Server des Skriptes gleichnamig sein. Dazu kann der Parameter sender genutzt werden. Ein Beispiel: Das Skript ist auf dem Server hoster.de gehostet, dort gibt es eine no-reply-Adresse, ein Mitarbeiter von firma.de nutzt das Online-Skript und schickt die Nachricht. Dann sind im Skript beim Aufruf der Methode send als Parameter zu übergeben:
      $mailerO = new Mailer ();  // Aufruf ohne Parameter
      $mailerO->send (Array(
        'sender'      => 'vorname.nachname@firma.de',
        'from'        => 'no-reply@hoster.de',
        'bcc'         => 'vorname2.nachname2@firma.de, vor2.nach2@firma2.de', vor3.nach3@firma2.de'
        'subject'     => '[Der Betreff] der Nachricht',
        'text'        => 'Der Text der Nachricht'
        ));
    
Dadurch ist die DKIM-Zertifizierung aller beteiligten Mail-Server gewährleistet. Weil aber als Absender-Adresse die no-reply-Adresse Empfänger irritieren könnte, wird oben in der Nachricht zur Information die Adresse des Absenders ergänzt angezeigt.

(2.2) Aufruf des Konstruktors MIT Parametern zur Formular-Anzeige vor dem Versand:

Zur Anzeige des Erfassungs-Formulars ist die Übergabe einiger Parameter im Format eines assoziativen Arrays nötig, also z.B. die im Formular genutzte Sprache (Standard: englisch) und die Absender-Adresse, die im Formular dann nicht mehr verändert werden kann:

      $parameters = Array(
        'language'    => 'de',
        'mailFrom'    => 'vorname.nachname@firma.de'
      );
      $mailerO = new Mailer ($parameters);  //Aufruf mit Parametern
    

(2.2.1) Nach Abschicken der Formulardaten (Button Abbruch oder Absenden) sollte wieder das Skript aufgerufen werden, in dem die Klasse Mailer eingebunden und der Konstruktor aufgerufen wurde. Soll aber in eine spezielle Methode oder in ein anderes Skript gesprungen werden, dann muss durch korrekte Angabe des Parameters formAction bereits beim ersten Aufruf gewährleistet sein, an die gewünschte Stelle zu gelangen. Beim erneuten Aufruf werden dann die erfassten Formular-Daten verarbeitet:

      // Aufruf mit Parametern:
      $mailerO = new Mailer (Array(
        'language'    => 'de',
        'mailFrom'    => 'vorname.nachname@firma.de',
        'formAction'  => 'script.php?action=method_name'
      ));
    
Im Skript muss dann eine Abfrage zum Wert des GET-Parameters action enthalten sein:
    if (isset($_GET['action']) && $_GET['action'] == 'method_name')
      method_name(); // Aufruf der Methode, in der die Mailer-Klasse eingebunden ist 
    

(2.2.2) Ein weiterer nützlicher Parameter ist mailReplyTo:
wird darin eine gültige Absender-Adresse übergeben und wird eine (davon unterschiedliche) Mail-Adresse in mailFrom übergeben, dann wird im Mail-Header als From-Adresse die mailFrom-Adresse verwendet, beim späteren Antworten auf diese Mail wird die mailReplyTo-Adresse genutzt.
In welchen Fällen sollte eine vom tatsächlichen Absender verschiedene From-Adresse übergeben werden?
Sollen Antworten nicht an den Absender, sondern an z. B. ein TeamMitglied gehen, wird dessen Adresse mit mailReplyTo übergeben.
Falls das aufrufende und sendende PHP-Skript auf einem anderen Server (z. B. hoster.de) gehostet ist als die Mail-Adresse des Absenders (z. B. nutzer@firma.de), wird der sendende Mail-Server auf hoster.de und alle empfangenden Mail-Server diese unterschiedlichen Mail-Server-Adressen erkennen und wegen Spam-Verdacht die DKIM-Zertifizierung verweigern.
Zur Abhilfe kann (mit existierender Weiterleitung bzw. Adresse, z.B. no-reply@hoster.de) als mailFrom eine Mail-Adresse auf dem sendenden Mail-Server bei hoster.de eingesetzt werden, was diese Parameterwerte ermöglichen:

    'mailFrom'    => 'no-reply@hoster.de'
    'mailReplyTo' => 'vorname.nachname@firma.de'
Nun steht im Mail-Header zu From: eine Adresse auf dem Server, von dem die Mail versendet wird:
"vorname.nachname@firma.de" <no-reply@hoster.de>
Nur dadurch erhält diese Nachricht von den übertragenden Mail-Servern die DKIM-Zertifizierung zur verdacht-freien Weiterleitung bis zum Empfänger-Mail-Server.

(2.2.3) Falls im Erfassungs-Formular Empfänger aus einer Liste ausgewählt werden sollen (statt jede ihrer Adressen komma-getrennt einzugeben), kann mit dem Parameter

'mailToSelect'    => (assoz. Array (String=>String) mit MailAdresse=>AnzeigeName oder leer Array(),
ein Array mit jeweils den Werten 'Anzeigename' => 'Mail-Adresse' übergeben werden. Aus diesen Werten wird dann die Auswahl-Liste im Formular generiert und nach Betätigung des Buttons [Verwenden] werden die Adressen der gewählten Empfänger im (nicht mehr bearbeitbaren) Erfassungsfeld Empfänger des Formulars eingetragen. Beispiel-Übergabe:
      'mailToSelect' => Array(
        'Duck, Donald' => 'donald.duck@entenhausen.de',
        'Gans, Gustav' => 'g.gans@bauernhof.org'
        )

(2.2.4) Zahlreiche Parameter zur Steuerung können in Form eines assoziativen Arrays beim Aufruf an den Mailer-Konstruktor übergeben werden. Hier nun die Übersicht aller möglichen Parameter zur Übergabe:

      'language'        => (String) 'de' oder 'en' (Standard),
      'mailFrom'        => (String) leer oder Absender-Mail-Adresse,
      'mailTo'          => (String) leer oder Empfänger-Mail-Adressen (komma-getrennt; Bcc versendet),
      'mailReplyTo'     => (String) leer oder Antwort-Mail-Adresse (für Mail-Header),
      'mailToSelect'    => (assoz. Array (String=>String) mit AnzeigeName => MailAdresse oder leer Array(),
      'mailCc'          => (String) leer oder Mail-Adressen von weiteren Kopie-Empfängern (komma-getr.; Cc),
      'mailBcc'         => '',
      'mailSubject'     => (String) leer oder Betreff-Zeile,
      'mailText'        => (String) leer oder unformatierter Nachrichten-Text,
      'mailAllowHtml'   => (String) HTML-Format '0'=nicht erlaubt (Standard) oder '1',
      'mailHtmlBody'    => (String) leer oder Nachrichten-Text im HTML-Format,
      'mailHtmlCss'     => (String) leer oder Nachrichten-Formatierungs-Stile im CSS-Format,
      'mailAttached'    => (Array) leer; wird im Formular ausgewählt,
      'mailEmbedded'    => (Array) leer; wird im Formular ausgewählt,
      'mailHeaders'     => (String-Array) zus. GÜLTIGE Angaben im Mail-Header (z. B. 'Precedence: bulk'),
      'mailAddBccText'  => (String) Info über Bcc-Empfänger (anonym; s.u.) oben ('1') oder unten ('2') im Mail-Text; sonst '0',
      'formAction'      => (String) leer (dann aktuelles Verzeichnis) oder Einsprung-Adresse
      'formTitle'       => (String) leer oder zusätzlicher Formular-Titel,
      'formToReadonly'  => (String) Formular-Eingabe im Empfängerfeld '0'=nicht erlaubt oder '1',
      'formTemplates'   => (String) '1' = Vorlagen anbieten, falls bereits gespeichert oder '0',
      'sendResult'      => (String) '1' = Zusätzlich Sende-Bericht an Absender senden, sonst '0',
      'sendToAnonym'    => (String) leer oder Anonyme-Empfänger-Gruppe, z. B. 'Ausgewählte Teamer',
      'sendResultSubject' => (String) leer oder spezieller Betreff des Sende-Berichts,
      'templateFolder'  => (String) absolute Adresse auf dem Skript-Host-Server als Ort zur Vorlagen-Speicherung,
      'templateUseIt'   => (String) '1' = Vorlagen anbieten, falls vom User gespeichert; sonst '0',
      'showHtml'        => (String) '1' = Sämtliche Bildschirmausgaben durch Mailer-Instanz; sonst '0')
    

(3) Informationen zur Programm-Entwicklung der Klasse Mailer

v1.1.3 September 2020

v1.1.2 Juni 2020

v1.1.1 Mai 2020

v1.1 Februar 2020

v1.0 Dezember 2019 - Januar 2020