Dokumentation: vlMailer – PHP-Formmailer

Diese Dokumentation bezieht sich auf die Formmailer- bzw. Kontaktformularklasse aus diesem Artikel: PHP-Formmailer – vlMailer – Individuell, Sicher, Einfach

Dies ist die offizielle Projekt-Dokumentation und Instruktion für die PHP-KLasse des Kontaktformular-Generators vlMailer. Für weitere Informationen und den Download folgen Sie dem obigen Link.

Dokumentation

vlMailer besteht aus einer umfangreichen PHP-Klasse mit dem Namen FORMMAILER. Sie organisiert Felder, Template, Versenden der Emails, Logbuch und Fehlerausgaben.

Der Formmailer besteht aus zwei grundlegenden Prozeduren: Ausgabe des HTML-Formulars und Empfang der Daten bzw. Senden einer Email-Nachricht.

Ausgabe:

  1. Laden der Felder (nachfolgend: Fieldset)
  2. Ausgabe der Felder

Versenden:

  1. Laden des Fieldset
  2. Vergleich des Fieldset mit Inhalten des abgeschickten Formulars
  3. Prüfen der Inhalte
  4. Ausgabe von Fehlermeldungen
  5. Versenden der Email

Die folgende Dokumentation ist optimiert für die Version 0.10 des vlMailers.

Folgende Vorraussetzungen werden gestellt (bei den meisten Webhostern erfüllt):

  • Webserver/Webspace mit PHP 5-Unterstützung (z.B. Apache + PHP 5)
  • Konfigurierter SMTP-Mailserver (z.B. Mercury)
  • PHP-Image- und -GD-Library (falls Captcha-Sicherung verwendet wird)

Fieldset

Das Fieldset ist ein mehrdimensionales assoziatives Array, welches alle Informationen über Formularfelder beinhaltet. Es wird beim Erstellen eines neuen Objekts der Klasse FORMMAILER als erstes eingelesen: mit dem Konstruktor.

Die Indizen des Arrays der ersten Dimension beschreiben den Namen eines Formularfeldes und sollten nur aus Buchstaben des ASCII-Zeichensatzes bestehen (a-z und A-Z). In der Reihenfolge, wie die Indizes geschrieben, werden die Felder im Formular ausgegeben.

Der Wert jedes Indizes besteht aus einem weiteren Array. In diesem werden Optionen für das Feld notiert. Hierbei gilt: Index ist Name der Option, Wert entspricht dem zugewiesenen Wert. Die verfügbaren Optionen werden durch die Option “type” (Pflichtangabe) bestimmt.

Die folgende Tabelle beschreibt, welche Typen es gibt und welche Optionen für diese verfügbar sind.

Typ (Option “type”) Verfügbare Optionen
text Typ erzeugt eine einzeilige Texteingabe. (HTML-Code: <input type=”text” />)

  • “symbol”: Bezeichnung für Feld (steht i.d.R. vor Eingabefeld); Darf beliebige Zeichen enthalten (UTF-8); Pflichtfeld
  • “required”: wenn auf “true” gesetzt, Feld ist Pflichfeld; Bei “false” nicht; Default: false
  • “maxlength”: Bestimmt maximale Anzahl an Zeichen; Erwartet Ganzzahl als Wert; Default: 20
  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “from” (Name des Absenders), “fromEmail” (Email-Adresse des Absenders), “subject” (Betreff der Nachricht), “none” (keine Rolle); Default: “none”
  • “value”: Vordefinierter Wert für Feld; Default: none
email Typ erzeugt eine mehrzeilige Texteingabe. (HTML-Code: <input type=”text” />)Überprüft Eingabe auf valide Email-Adresse.

  • “symbol”: Bezeichnung für Feld (steht i.d.R. vor Eingabefeld); Darf beliebige Zeichen enthalten (UTF-8); Pflichtfeld
  • “required”: wenn auf “true” gesetzt, Feld ist Pflichfeld; Bei “false” nicht; Default: false
  • “maxlength”: Bestimmt maximale Anzahl an Zeichen; Erwartet Ganzzahl als Wert; Default: 20
  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “from” (Name des Absenders), “fromEmail” (Email-Adresse des Absenders), “subject” (Betreff der Nachricht), “none” (keine Rolle); Default: “none”
  • “value”: Vordefinierter Wert für Feld; Default: none
textarea Typ erzeugt eine einzeilige Texteingabe. (HTML-Code: <textarea></textarea>)

  • “symbol”: Bezeichnung für Feld (steht i.d.R. vor Eingabefeld); Darf beliebige Zeichen enthalten (UTF-8); Pflichtfeld
  • “required”: wenn auf “true” gesetzt, Feld ist Pflichfeld; Bei “false” nicht; Default: false
  • “cols”: Anzahl an Zeichen pro Zeile; Erwartet Ganzzahl als Wert; Default: 30
  • “rows”: Anzahl an Zeilen; Erwartet Ganzzahl als Wert; Default: 7
  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “from” (Name des Absenders), “fromEmail” (Email-Adresse des Absenders), “subject” (Betreff der Nachricht), “none” (keine Rolle); Default: “none”
  • “value”: Vordefinierter Wert für Feld; Default: none
paragraph Typ erzeugt einen einfachen Textparagraphen.

  • “value”: Inhalt des Textparagraph; Default: “Information”
  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “from” (Name des Absenders), “fromEmail” (Email-Adresse des Absenders), “subject” (Betreff der Nachricht), “none” (keine Rolle); Default: “none”
captcha Typ erzeugt ein HTML-Image-Tag und ein einzeiliges Eingabefeld. Image-Tag bindet eine Grafik mit individuellem Sicherheitscode ein. Das Eingabefeld dient der Eingabe.

  • “options”: Array mit weiteren Optionen für Captcha-Grafik; Bestandteile des Arrays:
    • “ctype”: Typ der Captcha-Grafik; Mögliche Werte: “char” (Buchstaben-Code); Default: “char”
    • “width”: Breite der Grafik in Pixel; Erwartet Ganzzahl; Default: 150
    • “height”: Höhe der Grafik in Pixel; Erwartet Ganzzahl; Default: 50
    • “length”: Anzahl an anzuzeigenden Buchstaben in der Grafik; Erwartet Ganzzahl; Default: 7
    • “font”: Pfad zu einer FFT-Font-Datei; Schriftart für Buchsteben in der Grafik; Pflichtfeld
  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “from” (Name des Absenders), “fromEmail” (Email-Adresse des Absenders), “subject” (Betreff der Nachricht), “none” (keine Rolle); Default: “none”
submit Typ erzeugt einen Submit-Button (Absende-Button). (HTML-Code: <input type=”submit” />)

  • “role”: Rolle des Inhaltes des Feldes; Mögliche Werte: “submit” (Absende-Button), “none” (keine Rolle); Default: “submit”
  • “value”: Inhalt der Schaltfläche des Buttons; Default: “Abschicken”

Hinzu kommt die inoffizielle Option “name”, welche durch den Index jedes Feldes gesetzt wird. Die Option “type” ist ein Pflichtfeld und kann die Werte der linken Spalte annehmen.

Ein Beispiel für ein Fieldset, geschrieben in PHP, liegt dem offiziellen Download bei sieht so aus:

$fields = array(
	"name" => array(
		"symbol" => "Name* ",
		"type" => "text",
		"maxlength" => 20,
		"required" => true,
		"role" => "from",
		"value" => (isset($_POST['name'])) ? $_POST['name'] : ''
	),
	"email" => array(
		"symbol" => "Email-Adresse* ",
		"type" => "email",
		"maxlength" => 30,
		"required" => true,
		"role" => "fromEmail",
		"value" => (isset($_POST['email'])) ? $_POST['email'] : ''
	),
	"subject" => array(
		"symbol" => "Betreff* ",
		"type" => "text",
		"maxlength" => 50,
		"required" => true,
		"role" => "subject",
		"value" => (isset($_POST['subject'])) ? $_POST['subject'] : ''
	),
	"content" => array(
		"symbol" => "Nachricht* ",
		"type" => "textarea",
		"cols" => 30,
		"rows" => 7,
		"required" => true,
		"role" => "none",
		"value" => (isset($_POST['content'])) ? $_POST['content'] : ''
	),
	"info" => array(
		"type" => "paragraph",
		"value" => "Bitte geben Sie den Sicherheitscode ein: "
	),
	"captcha" => array(
		"type" => "captcha",
		"options" => array(
			"ctype" => "char",
			"length" => 5,
			"height" => 30,
			"width" => 110,
			"font" => "Bebas.ttf"
		)
	),
	"submit" => array(
		"name" => "submit",
		"value" => "Abschicken",
		"type" => "submit",
		"role" => "none"
	),
	"requiredfields" => array(
		"type" => "paragraph",
		"value" => "Die mit * gekennzeichneten Felder müssen ausgefüllt werden."
	)
);

Template

Die kleine Template-Engine von vlMailer ermöglicht es, einen HTML-Code oder Inhalt vor und nach einzelnen Feldern, Feldtiteln oder dem ganzen Formular ausgeben zu lassen.

Ein Template besteht, wie das Fieldset, aus einem Array. In der Version 0.10 hat es sieben verschiedene Indize:

  • “pre”: Inhalt vor einem gesamten Feld (Titel und Eingabefeld); Default: ‘<p class=”field”>
  • “after”: Inhalt nach einem gesamten Feld (Titel und Eingabefeld); Default: ‘</p>
  • “prename”: Inhalt vor dem Titel des Feldes (definiert durch “symbol”); Default: ‘<label class=”[class]” for=”[name]“>
  • “aftername”: Inhalt nach dem Titel des Feldes (definiert durch “symbol”); Default: ‘</label>
  • “preform”: Inhalt vor dem Formular; Default: ‘<fieldset id=”formmailer”><legend>Kontaktformular</legend><form action=”[action]” method=”[method]“>
  • “afterform”: Inhalt nach dem Formular; Default: ‘</form></fieldset>
  • “xhtml”: Bestimmt, ob das Formular in HTML oder XHTML ausgegeben werden soll; Mögliche Werte sind “true” (XHTML) und “false” (HTML); Default: “true”

Die Template-Engine unterstützt ein paar Platzhalter, welche bei der Ausgabe des Formulars durch bestimmte Werte ersetzt werden. Im folgenden eine Liste aller Variablen/Platzhalter:

  • [class]: Verfügbar in “pre” und “prename”; Fügt individuelle HTML-Klassen ein; Entsprechen meist dem Namen des Feldes plus Kennung wie “field” (bei “pre”) oder “fieldlabel” (bei “prename”)
  • [name]: Verfügbar in “prename”; Fügt Namen des Feldes ein
  • [action]: Verfügbar in “preform”; Fügt Pfad des Dokumentes ein (ermittelt durch PHP: “$_SERVER['SCRIPT_NAME']“)
  • [method]: Verfügbar in “preform”; Fügt “post” ein

Ein Beispiel für ein Template, geschrieben in PHP, liegt dem offiziellen Download (formmailer_config.php) bei und sieht so aus:

" for="[name]">',
	"aftersymbol" => '</label>',
	"pre" => '<p class="field [class]">',
	"after" => '</p>',
	"preform" => '<fieldset id="formmailer"><legend>Kontaktformular</legend><form action="[action]" method="[method]">',
	"afterform" => '</form></fieldset>',
	"xhtml" => true
);

Empfänger-Adresse

In Version 0.10 entspricht die Empfänger-Email-Adresse einer Zeichenkette (String). Die Zeichenkette wird einer Variable zugewiesen.

Im offiziellen Download wird die Email-Adresse so definiert (formmailer_config.php):

$to = "emailuser@emailserver.de";

In der Datei “formmailer_config.php” in Zeile 23 kann dieser Wert verändert werden.

Konfiguration

Die Konfiguration besteht aus den vorhergehenden Teilen Fieldset, Template und Empfänger-Adresse. Die entsprechenden PHP-Codes werden in einer Konfigurationsdatei abgespeichert werden. Um Kompatibilitätsprobleme zu vermeiden, sollte diese “formmailer_config.php” heißen.

Formular ausgeben und versenden

Das Ausgeben des Formulars findet durch Erstellen eines Objekts der Klasse FORMMAILER und darauf Aufrufen mit Ausgeben der Methode createForm() statt.

Damit PHP alle nötigen Daten dafür ermitteln kann, muss die Datei “formmailer.php” eingebunden werden. Diese Datei verknüpft Konfiguration, Klasse und einige Einstellungen.

Das HTML-Dokument erhält die Dateiendung *.php. In sie wird an erster Stelle (vor DocType etc.) folgender PHP-Code eingefügt:

<?php include "formmailer.php"; ?>

An der Stelle, an welcher das HTML-Formular von PHP ausgegeben werden soll, wird folgender Code eingefügt (egal wo):

<?php

if(!isset($_POST[$fields['submit']['name']])){

 echo $formmailer->createForm($template);

}elseif(isset($_SESSION['email_sent']) && $_SESSION['email_sent'] == true){

 echo '<p id="forminfo">Sie haben erst vor kurzem eine Nachricht versendet. Bitte warten Sie etwas.</p>';

}elseif(isset($_POST[$fields['submit']['name']])){

 $send = $formmailer->sendForm($_POST, $to);
 $errorlog = $formmailer->getErrorLog();
 if($errorlog != false && !$send){
 echo $errorlog;
 echo $formmailer->createForm($template);
 }elseif($send){
 $_SESSION['email_sent'] = true;
 echo '<p id="formsuccess">Danke, für Ihre Nachricht. Eine Email wurde erfolgreich verschickt.</p>';
 }

}

?>

Dieser Code beinhaltet einige prozedurbedingte Umwege, wie zum Beispiel bei erfolgreichen Verschicken der Email (Ausgabe einer Danksagung). Bei erfolgreicher Überprüfung der Eingaben in das Formular wird eine Nachricht versendet.

Dem offiziellen Download liegt ein Beispiel für das Dokument bei (contact.php):

<?php include "formmailer.php"; ?>
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <title>Kontaktformular</title>
 <link rel="stylesheet" type="text/css" href="formmailer_style.css" />
 </head>
 <body>

<?php

if(!isset($_POST[$fields['submit']['name']])){

 echo $formmailer->createForm($template);

}elseif(isset($_SESSION['email_sent']) && $_SESSION['email_sent'] == true){

 echo '<p id="forminfo">Sie haben erst vor kurzem eine Nachricht versendet. Bitte warten Sie etwas.</p>';

}elseif(isset($_POST[$fields['submit']['name']])){

 $send = $formmailer->sendForm($_POST, $to);
 $errorlog = $formmailer->getErrorLog();
 if($errorlog != false && !$send){
 echo $errorlog;
 echo $formmailer->createForm($template);
 }elseif($send){
 $_SESSION['email_sent'] = true;
 echo '<p id="formsuccess">Danke, für Ihre Nachricht. Eine Email wurde erfolgreich verschickt.</p>';
 }

}

?>

 </body>
</html>

Dieser Artikel wurde vertaggt mit , , , , , , , , , .
Kategorien: CSS, Internet, PHP, Software, Tutorial, Webdesign

Hat Ihnen dieser Artikel gefallen? - Dann abonnieren Sie vlblog um über neue Themen rund ums Web informiert zu werden.

Hinterlasse eine Antwort