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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect2 id="zend.validate.set.creditcard">
    <title>CreditCard</title>

    <para>
        <classname>Zend_Validate_CreditCard</classname> erlaubt es zu prüfen ob ein angegebener
        Wert eine Kreditkarten Nummer sein könnte.
    </para>

    <para>
        Eine Kreditkarte enthält verschiedene Elemente an Metadaten, inklusive ein Hologramm, die
        Accountnummer, Logo, Ablaufdatum, Sicherheitscode und den Namen des Kreditkartenbesitzers.
        Die Algorithmen für die Prüfung der Kombination an Metadaten sind nur der ausgebenden
        Firma bekannt, und sollten mit Ihnen zum Zwecke der Zahlung geprüft werden. Trotzdem ist es
        oft nützlich zu wissen ob eine akutell angegebene Nummer in den Bereich der möglichen
        Nummern fällt <emphasis>bevor</emphasis> so eine Überprüfung durchgeführt wird, und daher
        prüft <classname>Zend_Validate_CreditCard</classname> einfach ob die angegebene
        Kreditkartennummer entspricht.
    </para>

    <para>
        Für die Fälle in denen man ein Service hat, das tiefere Prüfungen durchführt, bietet
        <classname>Zend_Validate_CreditCard</classname> auch die Möglichkeit einen Service
        Callback anzuhängen der ausgeführt wird sobald die Kreditkartennummer vorbehaltlich als
        gültig geprüft wurde; dieser Callback wird dann ausgeführt, und sein Rückgabewert wird
        die komplette Gültigkeit erkennen.
    </para>

    <para>
        Die folgenden Kreditkarteninstitute werden akzeptiert:
    </para>

    <itemizedlist>
        <listitem>
            <para><emphasis>American Express</emphasis></para>
            <para><emphasis>China UnionPay</emphasis></para>
            <para><emphasis>Diners Club Card Blanche</emphasis></para>
            <para><emphasis>Diners Club International</emphasis></para>
            <para><emphasis>Diners Club US &amp; Canada</emphasis></para>
            <para><emphasis>Discover Card</emphasis></para>
            <para><emphasis>JCB</emphasis></para>
            <para><emphasis>Laser</emphasis></para>
            <para><emphasis>Maestro</emphasis></para>
            <para><emphasis>MasterCard</emphasis></para>
            <para><emphasis>Solo</emphasis></para>
            <para><emphasis>Visa</emphasis></para>
            <para><emphasis>Visa Electron</emphasis></para>
        </listitem>
    </itemizedlist>

    <note>
        <title>Ungültige Institute</title>

        <para>
            Die Institute <emphasis>Bankcard</emphasis> und <emphasis>Diners Club
                enRoute</emphasis> existieren nicht mehr. Deshalb werden Sie als ungültig erkannt.
        </para>

        <para>
            <emphasis>Switch</emphasis> wurde zu <emphasis>Visa</emphasis> umbenannt und wird daher
            auch als ungültig erkannt.
        </para>
    </note>

    <sect3 id="zend.validate.set.creditcard.options">
        <title>Unterstützte Optionen für Zend_Validate_CreditCard</title>

        <para>
            Die folgenden Optionen werden für <classname>Zend_Validate_CreditCard</classname>
            unterstützt:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>service</property></emphasis>: Ein Callback zu einem Online
                    Service welcher zusätzlich für die Prüfung verwendet wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>type</property></emphasis>: Der Typ der Kreditkarte der
                    geprüft werden soll. Siehe die folgende Liste an Instituten für Details.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.validate.set.creditcard.basic">
        <title>Grundsätzliche Verwendung</title>

        <para>
            Es gibt verschiedene Kreditkarten Institute wie mit
            <classname>Zend_Validate_CreditCard</classname> geprüft werden können. Standardmäßig
            werden alle bekannte Institute akzeptiert. Siehe das folgende Beispiel:
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_CreditCard();
if ($valid->isValid($input)) {
    // Die Eingabe scheint gültig zu sein
} else {
    // Die Eingabe ist ungültig
}
]]></programlisting>

        <para>
            Das oben stehende Beispiel würde alle bekannten Kreditkarten Institute als gültig
            erkennen.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.creditcard.institute">
        <title>Definierte Kreditkarte akzeptieren</title>

        <para>
            Manchmal ist es notwendig nur definierte Kreditkarten Institute zu akzeptieren statt
            alle; z.B wenn man einen Webshop hat der nur Visa und American Express Karten
            akzeptiert. <classname>Zend_Validate_CreditCard</classname> erlaubt einem exakt das zu
            tun, indem auf genau diese Institute limitiert wird.
        </para>

        <para>
            Um ein Limit zu verwenden kann man entweder spezifische Institute bei der Initiierung
            angeben, oder im nachhinein durch Verwendung von <methodname>setType()</methodname>.
            Jede kann verschiedene Argumente verwenden.
        </para>

        <para>
            Man kann ein einzelnes Institut angeben:
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_CreditCard(
    Zend_Validate_CreditCard::AMERICAN_EXPRESS
);
]]></programlisting>

        <para>
            Wenn man mehrere Institute erlauben will, dann kann man diese als Array angeben:
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_CreditCard(array(
    Zend_Validate_CreditCard::AMERICAN_EXPRESS,
    Zend_Validate_CreditCard::VISA
));
]]></programlisting>

        <para>
            Wie bei allen Prüfern kann man auch ein assoziatives Array an Optionen oder eine
            Instanz von <classname>Zend_Config</classname> angeben. In diesem Fall muß man die
            Institute mit dem Arrayschlüssel <property>type</property> angeben wie hier simuliert:
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_CreditCard(array(
    'type' => array(Zend_Validate_CreditCard::AMERICAN_EXPRESS)
));
]]></programlisting>

        <table id="zend.validate.set.creditcard.institute.table">
            <title>Konstanten für Kreditkarten Institute</title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Institut</entry>
                        <entry>Konstante</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry><emphasis>American Express</emphasis></entry>
                        <entry><constant>AMERICAN_EXPRESS</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>China UnionPay</emphasis></entry>
                        <entry><constant>UNIONPAY</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Diners Club Card Blanche</emphasis></entry>
                        <entry><constant>DINERS_CLUB</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Diners Club International</emphasis></entry>
                        <entry><constant>DINERS_CLUB</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Diners Club US &amp; Canada</emphasis></entry>
                        <entry><constant>DINERS_CLUB_US</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Discover Card</emphasis></entry>
                        <entry><constant>DISCOVER</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>JCB</emphasis></entry>
                        <entry><constant>JCB</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Laser</emphasis></entry>
                        <entry><constant>LASER</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Maestro</emphasis></entry>
                        <entry><constant>MAESTRO</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>MasterCard</emphasis></entry>
                        <entry><constant>MASTERCARD</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Solo</emphasis></entry>
                        <entry><constant>SOLO</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Visa</emphasis></entry>
                        <entry><constant>VISA</constant></entry>
                    </row>

                    <row>
                        <entry><emphasis>Visa Electron</emphasis></entry>
                        <entry><constant>VISA</constant></entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Man kann Institute auch im Nachhinein setzen oder hinzufügen indem die Methoden
            <methodname>setType()</methodname>, <methodname>addType()</methodname> und
            <methodname>getType()</methodname> verwendet werden.
        </para>

        <programlisting language="php"><![CDATA[
$valid = new Zend_Validate_CreditCard();
$valid->setType(array(
    Zend_Validate_CreditCard::AMERICAN_EXPRESS,
    Zend_Validate_CreditCard::VISA
));
]]></programlisting>

        <note>
            <title>Standard Institute</title>

            <para>
                Wenn bei der Initiierung kein Institut angegeben wird, dann wird
                <constant>ALL</constant> verwendet, welches alle Institute auf einmal verwendet.
            </para>

            <para>
                In diesem Fall ist die Verwendung von <methodname>addType()</methodname> sinnlos
                weil bereits alle Institute hinzugefügt wurden.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.creditcard.servicecheck">
        <title>Prüfung durch Verwendung einer fremden API</title>

        <para>
            Wie vorher erwähnt prüft <classname>Zend_Validate_CreditCard</classname> nur die
            Kreditkarten Nummer. Glücklicherweise bieten einige Institute online
            <acronym>API</acronym>s welche eine Kreditkarten Nummer durch Verwendung von Algorithmen
            prüfen kann, welche nicht öffentlich bekannt sind. Die meisten dieser Services sind zu
            bezahlen. Deshalb ist diese Art der Prüfung standardmäßig deaktiviert.
        </para>

        <para>
            Wenn man auf so eine <acronym>API</acronym> zugreift, kann man diese als Addon für
            <classname>Zend_Validate_CreditCard</classname> verwenden um die Sicherheit der
            Prüfung zu erhöhen.
        </para>

        <para>
            Um das zu tun muss man einfach einen Callback angeben der aufgerufen wird wenn die
            generische Prüfung erfolgreich war. Das verhindert das die <acronym>API</acronym> für
            ungültige Nummern aufgerufen wird, was wiederum die Performance der Anwendung erhöht.
        </para>

        <para>
            <methodname>setService()</methodname> setzt ein neues Service und
            <methodname>getService()</methodname> gibt das gesetzte Service zurück. Als
            Option für die Konfiguration kann man den Arrayschlüssel '<property>service</property>'
            bei der Initiierung verwenden. Für Details über mögliche Optionen kann man unter
            <link linkend="zend.validate.set.callback">Callback</link> nachsehen.
        </para>

        <programlisting language="php"><![CDATA[
// Die eigene Service Klasse
class CcService
{
    public function checkOnline($cardnumber, $types)
    {
        // einige online Prüfungen
    }
}

// Die Prüfung
$service = new CcService();
$valid   = new Zend_Validate_CreditCard(Zend_Validate_CreditCard::VISA);
$valid->setService(array($service, 'checkOnline'));
]]></programlisting>

        <para>
            Wie man sieht wird die Callback Methode mit der Kreditkarten Nummer als erster Parameter
            aufgerufen, und die akzeptierten Typen als zweiter Parameter.
        </para>
    </sect3>
</sect2>