repo_zf1/documentation/manual/de/module_specs/Zend_Validate-EmailAddress.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 20115 -->
<!-- Reviewed: no -->
<sect2 id="zend.validate.set.email_address">
    <title>Email Adresse</title>

    <para>
        <classname>Zend_Validate_EmailAddress</classname> erlaubt die Prüfung von Email Adressen.
        Der Prüfer teilt zuerst die Email Adresse in lokalen Teil @ hostname und versucht diese mit
        bekannten Spezifikationen für Email Adressen und Hostnamen zu prüfen.
    </para>

    <sect3 id="zend.validate.set.email_address.basic">
        <title>Normale Verwendung</title>

        <para>
            Ein Beispiel einer normalen Benutzung ist anbei:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
if ($validator->isValid($email)) {
    // Email Adresse scheint gültig zu sein
} else {
    // Email Adresse ist ungültig, drucke die Gründe hierfür
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            Das prüft die Email Adresse <varname>$email</varname> und gibt bei einem Fehler über
            <code>$validator->getMessages()</code> eine nützliche Fehlermeldung aus.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.options">
        <title>Optionen für die Prüfung von Email Adressen</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> unterstützt verschiedene Optionen
            welche entweder bei der Initiierung, durch Übergeben eines Arrays mit den betreffenden
            Optionen, gesetzt werden können, oder im Nachhinein, durch Verwendung von
            <methodname>setOptions()</methodname>. Die folgenden Optionen werden unterstützt:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>allow</emphasis>: Definiert welche Typen von Domain Namen akzeptiert
                    werden. Diese Option wird in Verbindung mit der hostname Option verwendet um
                    die Hostname Prüfung zu setzen. Für weitere Informationen über mögliche Werte
                    dieser Option sehen Sie bitte unter <link
                        linkend="zend.validate.set.hostname">Hostname</link> und mögliche
                    <constant>ALLOW</constant>* Konstanten. Der Standardwert dieser Option ist
                    <constant>ALLOW_DNS</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>hostname</emphasis>: Setzt die Hostname Prüfung mit welcher der Domain
                    Teil der Email Adresse geprüft wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mx</emphasis>: Definiert ob der MX Record vom Server erkannt werden
                    soll. Wenn diese Option auf <constant>TRUE</constant> definiert wird, dann
                    wird der MX Record verwendet um zu prüfen ob der Server Emails akzeptiert. Der
                    Standardwert dieser Option ist <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>deep</emphasis>: Definiert ob die MX Records des Server durch eine
                    tiefe Prüfung verifiziert werden sollen. Wenn diese Option auf
                    <constant>TRUE</constant> gesetzt wird, dann werden zusätzlich zum MX Record
                    auch die A, A6 und <constant>AAAA</constant> Records verwendet um zu prüfen ob
                    der Server Emails akzeptiert. Der Standardwert dieser Option ist
                    <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>domain</emphasis>: Definiert ob der Domain Teil geprüft werden soll.
                    Wenn diese Option auf <constant>FALSE</constant> gesetzt wird, dann wird nur der
                    lokale Teil der Email Adresse geprüft. In diesem Fall wird die Hostname Prüfung
                    nicht aufgerufen. Der Standardwert dieser Option ist <constant>TRUE</constant>.
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => false));
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.complexlocal">
        <title>Komplexe lokale Abschnitte</title>

        <para>
            <classname>Zend_Validate_EmailAdress</classname> prüft jede gültige Email Adresse mit
            RFC2822. Gültige Email Adressen sind zum Beispiel
            <code>bob@domain.com</code>, <code>bob+jones@domain.us</code>,
            <code>"bob@jones"@domain.com</code> und <code>"bob jones"@domain.com</code>
        </para>

        <para>
            Einige Email Formate werden aktuell nicht geprüft (z.B. Zeilenumbruch Zeichen oder ein
            "\" Zeichen in einer Email Adresse).
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.purelocal">
        <title>Nur den lokalen Teil prüfen</title>

        <para>
            Wenn man will das <classname>Zend_Validate_EmailAddress</classname> nur den lokalen Teil
            der Email Adresse prüfen soll, und die Prüfung des Hostnamens ausschalten will, kann man
            die <property>domain</property> Option auf <constant>FALSE</constant> setzen. Das
            zwingt <classname>Zend_Validate_EmailAddress</classname> den Hostname Teil der Email
            Adresse nicht zu prüfen.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => FALSE));
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.hostnametype">
        <title>Prüfen von unterschiedlichen Typen von Hostnamen</title>

        <para>
            Der Teil des Hostnamens einer Email Adresse wird mit <link
                linkend="zend.validate.set.hostname"><classname>Zend_Validate_Host</classname></link>
            geprüft. Standardmäßig werden nur DNS Hostnamen in der Form <code>domain.com</code>
            akzeptiert, aber wenn es gewünscht ist, können auch IP Adressen und lokale Hostnamen
            auch akzeptiert werden.
        </para>

        <para>
            Um das zu tun, muß eine <classname>Zend_Validate_EmailAddress</classname> Instanz
            erstellt werden der ein Parameter übergeben wird, um den Typ des Hostnamens anzugeben
            der akzeptiert werden soll. Mehr Details sind in
            <classname>Zend_Validate_Hostname</classname> inkludiert, zusammen mit einem Beispiel,
            wie DNS und lokale Hostnamen, akzeptiert werden wie im Beispiel das anbei steht:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(
                    Zend_Validate_Hostname::ALLOW_DNS |
                    Zend_Validate_Hostname::ALLOW_LOCAL);
if ($validator->isValid($email)) {
    // Email Adresse scheint gültig zu sein
} else {
    // Email ist ungültig; Gründe ausdrucken
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.checkacceptance">
        <title>Prüfen ob der Hostname aktuell Emails akzeptiert</title>

        <para>
            Nur weil eine Email Adresse im richtigen Format ist, heißt das notwendigerweise nicht
            das die Email Adresse aktuell auch existiert. Um dieses Problem zu lösen, kann MX
            Prüfung verwendet werden um zu prüfen ob ein MX (Email) Eintrag im DNS Eintrag für den
            Hostnamen der Email existiert. Das zeigt ob der Hostname Emails akzeptiert, sagt aber
            nicht aus, ob die genaue Email Adresse selbst gültig ist.
        </para>

        <para>
            Die MX Prüfung ist standardmäßig nicht eingeschaltet. Um die MX Prüfung einzuschalten
            kann ein zweiter Parameter an den <classname>Zend_Validate_EmailAddress</classname>
            Konstruktor übergeben werden.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(
    array(
        'allow' => Zend_Validate_Hostname::ALLOW_DNS,
        'mx'    => true
    )
);
]]></programlisting>

        <note>
            <title>Die MX Prüfung unter Windows</title>

            <para>
                In Windows Umgebungen ist die MX Prüfung nicht vorhanden wenn <acronym>PHP</acronym>
                5.3 oder höher verwendet wird. Unter <acronym>PHP</acronym> 5.3 wird die MX
                Prüfung nicht verwendet, selbst wenn diese in den Optionen aktiviert wurde.
            </para>
        </note>

        <para>
            Alternativ kann entweder <constant>TRUE</constant> oder <constant>FALSE</constant> an
            <code>$validator->setValidateMx()</code> übergeben werden um die MX Prüfung ein- oder
            auszuschalten.
        </para>

        <para>
            Durch das einschalten dieser Option werden Netzwerk Funktionen verwendet um zu Prüfen
            ob ein MX Eintrag am Hostnamen der Email Adresse existiert, welche geprüft werden soll.
            Vorsicht davor, das hierbei das eigene Skript langsamer wird.
        </para>

        <para>
            Manchmal gibt die Prüfung auf MX Records <constant>FALSE</constant> zurück, selbst wenn
            Emails akzeptiert werden. Der Hintergrund dieses Verhaltens ist, das der Server Emails
            akzeptieren kann, selbst wenn er keinen MX Record anbietet. In diesem Fall kann er A, A6
            oder <constant>AAAA</constant> Records anbieten. Um es
            <classname>Zend_Validate_EmailAddress</classname> zu erlauben auch auf diese anderen
            Records zu prüfen, muss man die tiefe MX Prüfung einschalten. Das kann man durch Setzen
            der <property>deep</property> Option bei der Initialisierung, oder durch Verwendung von
            <methodname>setOptions()</methodname> tun.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(
    array(
        'allow' => Zend_Validate_Hostname::ALLOW_DNS,
        'mx'    => true,
        'deep'  => true
    )
);
]]></programlisting>

        <warning>
            <title>Performance Warnung</title>

            <para>
                Man sollte darauf achten das die Aktivierung der MX Prüfung das Skript langsamer
                machen wird, weil es Netzwerk Funktionen verwendet. Die Aktivierung der tiefen
                Prüfung macht das Skript sogar noch langsamer da es im angegebenen Server nach
                3 zusätzlichen Typen sucht.
            </para>
        </warning>

        <note>
            <title>Disallowed IP addresses</title>

            <para>
                Man sollte beachten das die MX Prüfung nur für externe Server akzeptiert wird. Wenn
                die tiefe MX Prüfung aktiviert wird, dann werden IP Adressen wie
                <command>192.168.*</command> oder <command>169.254.*</command> nicht akzeptiert.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.email_address.validateidn">
        <title>Internationale Domain Namen prüfen</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> prüft auch internationale Zeichen
            prüfen, die in einigen Domains existieren. Dies ist als Unterstützung für
            Internationale Domain Namen (IDN) bekannt. Standardmäßig ist das eingeschaltet. Das
            kann aber ausgeschaltet werden indem eine Einstellung geändert wird über das interne
            <classname>Zend_Validate_Hostname</classname> Objekt das innerhalb von
            <classname>Zend_Validate_EmailAddress</classname> existiert.
        </para>

        <programlisting language="php"><![CDATA[
$validator->getHostnameValidator->setValidateIdn(false);
]]></programlisting>

        <para>
            Weitere Informationen über die Verwendung von <methodname>setValidateIdn()</methodname>
            gibt es in der <classname>Zend_Validate_Hostname</classname> Dokumentation.
        </para>

        <para>
            Es sollte darauf geachtet werden das IDNs nur geprüft werden wenn erlaubt ist DNS
            Hostnamen zu prüfen.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.validatetld">
        <title>Top Level Domains prüfen</title>

        <para>
            Standardmäßig wird ein Hostname mit einer List von bekannten TLDs geprüft. Das ist
            standardmäßig aktiviert, kann aber ausgeschaltet werden indem die Einstellung über das
            interne <classname>Zend_Validate_Hostname</classname> geändert wird, das innerhalb von
            <classname>Zend_Validate_EmailAddress</classname> existiert.
        </para>

        <programlisting language="php"><![CDATA[
$validator->getHostnameValidator->setValidateTld(false);
]]></programlisting>

        <para>
            Mehr Informationen über die Verwendung von <methodname>setValidateTld()</methodname>
            gibt es in der <classname>Zend_Validate_Hostname</classname> Dokumentation.
        </para>

        <para>
            Es sollte darauf geachtet werden das TLDs nur geprüft werden wenn es auch erlaubt ist
            DNS Hostnamen zu prüfen.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.setmessage">
        <title>Setzen von Meldungen</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> verwendet auch
            <classname>Zend_Validate_Hostname</classname> um den Teil des Hostnamens einer
            angegebenen Email Adresse zu prüfen. Ab Zend Framework 1.10 kann man Meldungen für
            <classname>Zend_Validate_Hostname</classname> auch von innerhalb
            <classname>Zend_Validate_EmailAddress</classname> setzen.
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setMessages(array(
    Zend_Validate_Hostname::UNKNOWN_TLD => 'Ich kenne die TLD nicht')
);
]]></programlisting>

        <para>
            Vor Zend Framework 1.10 musste man die Meldungen einem eigenen
            <classname>Zend_Validate_Hostname</classname> hinzufügen, und dann diese Prüfung in
            <classname>Zend_Validate_EmailAddress</classname> setzen um die eigenen Meldungen
            zurückzubekommen.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->