ReadMe für Form E-Mail 3.5

Was ist Form E-Mail?
Einrichten von Form E-Mail
Einstellungen
Individuelle Formularfelder
Templates anpassen

Was ist Form E-Mail?

Form E-Mail ist ein in PHP programmierter Form-Mailer, der speziell darauf ausgerichtet ist, ein Kontaktformular zu verarbeiten. Unter Kontaktformular verstehe ich ein Formular mit Feldern für Name und E-Mail-Adresse des Absenders, eines für den Betreff und ein weiteres für den Text der Mail.
Auf diese Weise müssen Sie zum Beispiel nicht überall auf Ihrer Homepage Ihre E-Mail-Adresse angeben und sie so nicht der Gefahr aussetzen, ein Opfer von Spammern zu werden.

Nach oben

Einrichten von Form E-Mail

Sie brauchen als erstes ein HTML-Formular. Dieses muss mindestens diese Felder enthalten:

Feldname	Zweck
email	E-Mail-Adresse des Absenders
name	Name des Absenders
text	Text der E-Mail

Sie können außerdem noch ein Feld namens subject anlegen. Hier kann ein Betreff für die Mail eingegeben werden. Wenn Sie auf dieses Feld verzichten, erhalten die E-Mails automatisch den in $default_subject definierten Betreff (s.u.).
Weiterhin ist noch ein Feld namens recipient möglich. Dieses Feld enthält einen Alias-Empfänger. Wie das funktioniert, können Sie bei der Beschreibung der Einstellung $aliases lesen.

Zusätzlich können Sie die vorgegebenen Formularfelder mit individuellen ergänzen.

Wenn Sie Captchas (zufällige Zeichenfolgen, die der Benutzer vor dem Absenden des Formulars eingeben muss, um Spambots auszuschließen) benutzen wollen (siehe unten), müssen Sie im Formular die Datei captcha.php als Bild einbinden (<img>-Tag). Bedenken Sie, dass Sie diese Datei auch in den Templates einbinden müssen!

Das Formular muss dann noch mit POST die Daten an die Datei mailer.php (oder wie Sie die Datei genannt haben) senden.

Ein beispielhaftes Formular finden Sie in der Datei formular.htm.

Die Adresse, an der die mit Form E-Mail erzeugte Mail gesendet werden soll, wird in der Datei config.php festgelegt. Öffnen Sie die Datei mit einem beliebigen Editor und suchen Sie nach dieser Zeile:

$mailto = '';

Geben Sie zwischen den einfachen Anführungszeichen die Adresse an, an die die Mail gehen soll. Wenn die Mail an mehrere Empfänger gehen soll, so trennen Sie die einzelnen E-Mail-Adressen ganz einfach durch Semikolons.

Sie haben nun Form E-Mail für die Standard-Nutzung konfiguriert. Form E-Mail lässt sich jedoch noch feiner konfigurieren. Mehr dazu finden Sie in den nächsten Abschnitten.

Nach oben

Einstellungen

Empfänger

Einstellung	Beschreibung
`$mailto`	siehe oben
`$aliases`	Hier können Sie eine Alias-Namen für Empfänger angeben. Soll einem Alias mehrere Empfänger zugeordnet werden, gilt dasselbe wie für `$mailto`. Die Aliase werden mit Hilfe eines assoziativen PHP-Arrays definiert. Da es wohl einige gibt, die von so etwas keine Ahnung haben und ich es nicht gut erklären kann, hier ein Beispiel: `array('info' => 'info@example.com', 'support' => 'support@example.com', 'alle' => 'info@example.com; support@example.com')`

Allgemeines

Einstellung	Beschreibung
`$default_subject`	Der Standard-Betreff. Dieser wird verwendet, wenn der Benutzer keinen Betreff für seine Mail angegeben hat.
`$friendly_sender`	Wenn 1, wird die E-Mail-Adresse des Autors der Mail als Absender angegeben. Bei 0 erscheint das, was der Server als Absender einträgt und die E-Mail-Adresse des Absenders wird in den `Reply-To`-Header eingetragen, so dass beim Antworten auf die E-Mail schon der richtige Empfänger eingetragen wird. Wenn 2, wird zusätzlich noch der Name als Absender angegeben. Bitte setzen Sie diese Option nur auf 0, wenn es wirklich sein muss!
`$line_break`	Legt fest, ab wievielen Zeichen ein automatischer Zeilenumbruch durchgeführt werden soll (0 für keine Zeilenumbrüche).
`$add_header`	Legt beim Wert 1 fest, ob Form E-Mail Informationen zur Zeichencodierung, MIME-Version usw. in den Mail-Header schreiben soll. Bitte setzen Sie diese Option nur auf 0, wenn es wirklich sein muss!
`$timeformat`	Legt das Aussehen der Zeitangaben der Mail fest. Was hier alles möglich ist, finden Sie im PHP-Handbuch bei der Beschreibung zu `strftime()`. Beachten Sie bitte, dass bei neueren PHP-Versionen, trotz deutscher Spracheinstellungen, die Namen von Wochentagen und Monaten englisch dargestellt werden. Es handelt sich hierbei aber um ein allgemeines Problem.
`$return_url`	Geben Sie hier die URL einer Seite an, auf die nach dem erfolgreichen Versenden einer Mail weitergeleitet werden soll. Wenn Sie hier nichts angeben, wird eine per Template formatierte Seite angezeigt. Achtung: Benutzen Sie hier nach Möglichkeit absolute URLs! Ich habe zwar etwas eingebaut, was hier relative URLs in absolute umwandelt, um dem HTTP-Standard gerecht zu werden, aber ich garantiere nicht, dass diese Umwandlung immer einwandfrei funktioniert. Seien Sie bei relativen URLs also sehr vorsichtig und verwenden Sie im Fehlerfall absolute.
`$allowed_envs`	Geben Sie hier die Server-Umgebungsvariablen, die im Mailtext angezeigt werden dürfen, als normales PHP-Array an (siehe auch die Erläuterungen zur Template-Datei mail.txt). Beispiel: `array('HTTP_USER_AGENT','REMOTE_ADDR')`
`$charset`	Geben Sie hier den Zeichensatz, der für die E-Mail verwendet werden soll, an.
`$timezone`	Geben Sie hier Ihre Zeitzone an (dies ist bei neueren PHP-Versionen nötig, da ansonsten eine Fehlermeldung auftreten kann).

Längenüberprüfungen

Einstellung	Beschreibung
`$name_min`	Geben Sie hier an, wie lang der vom Benutzer eingebene Name mindestens sein muss (0 = beliebig lang)
`$subject_min`	Geben Sie hier an, wie lang der vom Benutzer eingebene Betreff mindestens sein muss (0 = beliebig lang)
`$text_min`	Geben Sie hier an, wie lang der vom Benutzer eingebene Text mindestens sein muss (0 = beliebig lang)
`$name_max`	Geben Sie hier an, wie lang der vom Benutzer eingebene Name höchstens sein darf (0 = beliebig lang)
`$subject_max`	Geben Sie hier an, wie lang der vom Benutzer eingebene Betreff höchstens sein darf (0 = beliebig lang)
`$text_max`	Geben Sie hier an, wie lang der vom Benutzer eingebene Text höchstens sein darf (0 = beliebig lang)

Sicherheit

Einstellung	Beschreibung
`$check_referer`	Wenn > 0, überprüft Form E-Mail die Host-Angabe im HTTP-Referer. Das ist nützlich, wenn Sie verhindern wollen, dass irgendjemand Ihr Script für sich ausnutzt.
`$referer_ok`	Geben Sie hier die Hosts an, von denen Form E-Mail aus aufgerufen werden darf (zum Beispiel www.example.com). Trennen Sie mehrere Hosts durch Semikolons. Achtung: Mit einer Referer-Prüfung kann man zwar unbedarfte Anwender abschrecken, aber wirklich zuverlässig ist diese Methode nicht, da sich der Referer fälschen lässt oder auch komplett fehlen kann.

Mails speichern

Einstellung	Beschreibung
`$store_mails`	Wenn > 0, speichert Form E-Mail die Mails nach dem Versenden noch auf dem Server als Datei ab.
`$store_mails_dir`	Geben Sie hier das Verzeichnis an, in dem Form E-Mail die Mails speichern soll (Standard ist stored_mails). Die Dateinamen bestehen aus dem Präfix, dem Absender, dem Betreff, der Uhrzeit und einem eindeutigen Wert.
`$store_mails_prefix`	Geben Sie hier einen Präfix an, der den Dateinamen der gespeicherten Mails vorangestellt werden soll (Standard ist feml_).
`$store_mails_max`	Geben Sie hier die Zahl der Mails an, die maximal aufbewahrt werden sollen. Wenn Sie hier 0 angeben, werden keine Mails gelöscht. Die Mail-Dateien werden anhand des mit `$store_mails_prefix` definierten Präfixes erkannt.

Captchas

Einstellung	Beschreibung
`$captcha_enable`	Wenn > 0, wird die Captcha-Überprüfung aktiviert.
`$captcha_case`	Wenn 1, wird bei Captchas auf Groß- und Kleinschreibung geachtet. Beachten Sie bitte, dass bei deaktiverter Einstellung im Captcha selbst immer noch Groß- und Kleinbuchstaben angezeigt werden - lediglich bei der Auswertung wird die Groß- und Kleinschreibung nicht berücksichtigt.
`$captcha_max`	Wenn > 0, ist nur eine bestimmte Anzahl von Fehlversuchen bei der Eingabe des Captcha-Texts möglich.
`$captcha_length`	Geben Sie hier die Länge des Captcha-Textes an.
`$captcha_width`	Geben Sie hier die Breite des Captcha-Bilds an (in Pixeln). Dieser Wert wird überschrieben, wenn `$captcha_image_bg` gesetzt ist.
`$captcha_height`	Geben Sie hier die Höhe des Captcha-Bilds an (in Pixeln). Dieser Wert wird überschrieben, wenn `$captcha_image_bg` gesetzt ist.
`$captcha_angle`	Geben Sie hier den Winkel-Bereich an, in dem der Captcha-Text ausgerichtet werden soll. Es wird ein zufälliger Wert aus diesem Bereich ausgewählt.
`$captcha_x`	Geben Sie hier den Bereich an, in dem sich der horizontale Startpunkt des Captcha-Texts befinden soll. Es wird ein zufälliger Wert aus diesem Bereich ausgewählt.
`$captcha_y`	Geben Sie hier den Bereich an, in dem sich der vertikale Startpunkt des Captcha-Texts befinden soll. Es wird ein zufälliger Wert aus diesem Bereich ausgewählt.
`$captcha_possible`	Geben Sie hier die möglichen Zeichen des Captcha-Texts an. Standardmäßig vorgegeben ist 'ABCDEFGHJKLMNPRSTUVWXYZabcdefghijkmnpqrstuvwxyz23456789'.
`$captcha_font`	Schriftart für den Captcha-Text. Geben Sie hier den Pfad zu einer .ttf-Datei an. Standardmäßig ist hier die mitgelieferte XFILES.TTF angegeben.
`$captcha_font_size`	Geben Sie hier die Schriftgröße des Captcha-Textes an.
`$captcha_lines`	Wenn > 0, werden zufällige Störlinien in das Captcha-Bild eingefügt.
`$captcha_color_bg`	Geben Sie hier die RGB-Werte (in Form eines PHP-Arrays) der Hintergrundfarbe des Captcha-Bilds an.
`$captcha_color_text`	Geben Sie hier die RGB-Werte (in Form eines PHP-Arrays) der Textfarbe des Captcha-Bilds an.
`$captcha_image_bg`	Hier können Sie, wenn Sie möchten, ein Hintergrundbild für das Captcha-Bild angeben. Diese Option überschreibt `$captcha_length` und `$captcha_height` mit den Angaben aus dem Bild.

Fehlermeldungen

Einstellung	Beschreibung
`$err_nothing`	Der Benutzer hat überhaupt nichts eingegeben
`$err_no_name`	Der Benutzer hat keinen Namen angegeben
`$err_no_email`	Der Benutzer hat keine E-Mail-Adresse angegeben
`$err_invalid_email`	Der Benutzer hat eine von der Syntax her ungültige E-Mail-Adresse angegeben
`$err_no_text`	Der Benutzer hat keinen Text angegeben
`$err_name_short`	Der vom Benutzer eingegebene Name ist nicht lang genug
`$err_subject_short`	Der vom Benutzer eingegebene Betreff ist nicht lang genug
`$err_text_short`	Der vom Benutzer eingegebene Text ist nicht lang genug
`$err_name_long`	Der vom Benutzer eingegebene Name ist nicht zu lang
`$err_subject_long`	Der vom Benutzer eingegebene Betreff ist zu lang
`$err_text_long`	Der vom Benutzer eingegebene Text ist zu lang
`$err_send_error`	Die Mail konnte nicht versendet werden
`$err_only_post`	Form E-Mail darf nur mit `POST` aufgerufen werden
`$err_referer_not_ok`	Der im HTTP-Referer angegebene Host darf keine Mails über das Script senden
`$err_indiv_errmsg_miss`	Eine Fehlermeldung für die individuellen Formularfelder wurde nicht definiert (die Variable `{INDIVIDUAL}` gibt das Formularfeld an, `{ERRMSG}` die fehlende Fehlermeldung).
`$err_captcha_incorrect`	Der vom Benutzer eingegebene Captcha-Code ist nicht korrekt
`$err_captcha_max`	Der Benutzer hat den Captcha-Code zu oft falsch eingegeben
`$err_captcha_disabled`	Wird angezeigt, wenn captcha.php aufgerufen wird und Captchas eigentlich deaktiviert sind.
`$err_captcha_session_failure`	Wird angezeigt, wenn keine Session-Variablen gefunden werden konnten.

Pfade zu Templates

Einstellung	Beschreibung
`$tpl_mail`	Template für die Mail
`$tpl_sent`	Die Mail wurde erfolgreich versendet
`$tpl_user_error`	Der Benutzer hat etwas falsch gemacht
`$tpl_fatal`	Es ist ein Fehler aufgetreten, den der Benutzer nicht mehr beheben kann

Nach oben

Individuelle Formularfelder

Seit Version 3.5 ist es möglich, in Form E-Mail zusätzlich zu den vorgegebenen Formularfeldern für Name, E-Mail-Adresse, Betreff und Text eigene Formularfelder zu definieren, die dann von Form E-Mail verarbeitet und in die Mail eingefügt werden.
Wie Form E-Mail diese Formularfelder behandelt, wird über verschiedene Optionen gesteuert, so ist es möglich die Länge des Inhalts zu prüfen, den Inhalt gegen einen regulären Ausdruck und gegen eine frei definierbare PHP-Funktion zu prüfen und am Ende den Inhalt noch durch eine PHP-Funktion aufzubereiten.

Die Konfiguration der individuellen Formularfelder geschieht über das PHP-Array $user_fields in config.php. Sie benötigen zunächst den Namen des Formularfeldes, also das, was Sie im HTML-Formular als Namen angeben. Nehmen wir an, Sie haben folgenden HTML-Code für ein Formularfeld:

<input type="text" name="beruf" />

Der Name des Feldes lautet also beruf. Dies benötigen wir für die weitere Definition.

Sie können nun verschiedene Prüfwerte definieren, mit denen Form E-Mail den Inhalt des Formularfeldes überprüft und ggf. eine Fehlermeldung ausgibt. Diese werden in der folgenden Tabelle erläutert (die Tabelle geht der Einfachheit halber weiterhin vom Formularfeld beruf aus - Sie müssen dies natürlich anpassen!):

Einstellung	Beschreibung
`$user_fields['beruf']['min']`	Geben Sie hier an, wie lang der vom Benutzer eingebene Wert mindestens sein muss
`$user_fields['beruf']['max']`	Geben Sie hier an, wie lang der vom Benutzer eingebene Wert höchstens sein darf
`$user_fields['beruf']['required']`	Geben Sie hier den Wert 1 an, wenn das Formularfeld ausgefüllt sein muss. Wenn Sie hier eine 0 oder die Option weglassen, ist das Feld optional.
`$user_fields['beruf']['regex']`	Geben Sie hier einen Perl-kompatiblen regulären Ausdruck zur Prüfung des Wertes ein. Der Ausdruck wird direkt an `preg_match()` weitergegeben.
`$user_fields['beruf']['check']`	Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, durch die der Wert geprüft werden soll.

Weiterhin müssen Sie noch diverse Fehlermeldungen definieren (als Unter-Array). Das Definieren dieser Fehlermeldungen ist Pflicht (Sie müssen jedoch nur die Fehlermeldungen zu den Dingen definieren, die auch wirklich geprüft werden).

Einstellung	Beschreibung
`$user_fields['beruf']['errors']['too_short']`	Der vom Benutzer eingegebene Wert ist nicht lang genug
`$user_fields['beruf']['errors']['too_long']`	Der vom Benutzer eingegebene Wert ist zu lang
`$user_fields['beruf']['errors']['not_set']`	Das Formularfeld ist ein Pflichtfeld und es wurde nicht ausgefüllt.
`$user_fields['beruf']['errors']['match_fail']`	Die Überprüfung des Wertes durch den regulären Ausdruck ist fehlgeschlagen.
`$user_fields['beruf']['errors']['check_fail']`	Die Überprüfung des Wertes durch die PHP-Funktion ist fehlgeschlagen.

Zusätzlich sind noch die folgenden Einstellungen möglich:

Einstellung	Beschreibung
`$user_fields['beruf']['prepare']`	Geben Sie hier eine selbst definierte PHP-Funktion (als Zeichenkette) an, die den Wert des Formularfeldes nach den Prüfungen noch verändern (bspw. kann man hier Funktionen angeben, die alle Buchstaben in Großbuchstaben umwandelt).
`$user_fields['beruf']['tpl_var']`	Geben Sie hier die Template-Variable an, die in den Templates durch den Wert des Formularfeldes ersetzt werden soll. Wenn Sie hier nichts angeben, wird ein Standardwert verwendet (im Fall des Formularfeldes beruf wäre das dann `USER_beruf`).

Sie müssen die individuellen Formularfelder nun noch in Ihrem Mail-Formular und in den Templates ergänzen.

Nach oben

Templates anpassen

Die Anpassung der Ausgaben von Form E-Mail erfolgt über Templates (englisch für "Vorlagen"). Jede der Templates enthält Variablen der Form {VARIABLENNAME}, die dann von Form E-Mail durch entsprechende Daten ersetzt werden.

Hier nun eine Auflistung der einzelnen Templates und der verwendeten Variablen (ohne geschweifte Klammern):

Datei	Zweck	Verwendete Variablen
fatal.htm	Wird angezeigt, wenn ein Fehler aufgetreten ist, den der Benutzer nicht mehr beheben kann	ERROR Die Fehlermeldung
mail.txt	Legt das Aussehen der Mail fest	EMAIL Die eingegebene E-Mail-Adresse NAME Der eingegebene Name SUBJECT Der Betreff der Mail TEXT Der eingegebene Mail-Text TIME Die formatierte Zeitangabe Weiterhin können Sie hier die definierten Variablen der individuellen Formularfelder (das, was Sie in `tpl_var` angegeben) verwenden. Zusätzlich können Sie hier durch Variablen, die mit ENV_ beginnen, Server-Umgebungsvariablen im Text einfügen (siehe auch Konfigurationsvariable `$allowed_envs`.
sent.htm	Wird angezeigt, wenn die Mail erfolgreich versendet wurde	EMAIL Die eingegebene E-Mail-Adresse MAIL Die komplette Mail, so wie sie versendet wurde (natürlich ohne Header) NAME Der eingegebene Name SUBJECT Der Betreff der Mail TEXT Der eingegebene Mail-Text TIME Die formatierte Zeitangabe Weiterhin können Sie hier die definierten Variablen der individuellen Formularfelder (das, was Sie in `tpl_var` angegeben) verwenden.
user_error.htm	Wird angezeigt, wenn der Benutzer einen Fehler gemacht hat, der sich aber noch beheben lässt (zum Beispiel wenn ein Formularfeld nicht ausgefüllt wurde)	EMAIL Die eingegebene E-Mail-Adresse ERROR Die Fehlermeldung NAME Der eingegebene Name SUBJECT Der Betreff der Mail TEXT Der eingegebene Mail-Text Weiterhin können Sie hier die definierten Variablen der individuellen Formularfelder (das, was Sie in `tpl_var` angegeben) verwenden. Zusätzlich ist es möglich, einen Bereich, der nur angezeigt werden soll, wenn Captchas aktiviert sind, anzuzeigen, indem Sie diesen in folgenden Block einschließen (der `{ELSE}`-Teil ist optional): `{IF CAPTCHA}Captchas sind aktiviert{ELSE}Captchas sind nicht aktiviert{ENDIF}`

Versionshistorie

Homepage:	http://www.patshaping.de/
E-Mail:	patrick@patshaping.de