repo_zf1/documentation/manual/de/module_specs/Zend_Service_Akismet.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.service.akismet">
    <title>Zend_Service_Akismet</title>

    <sect2 id="zend.service.akismet.introduction">
        <title>Einführung</title>

        <para>
            <classname>Zend_Service_Akismet</classname> bietet einen Client für die
            <ulink url="http://akismet.com/development/api/">Akismet <acronym>API</acronym></ulink>.
            Der Akismet Service wird verwendet um herauszufinden ob hereinkommende Daten
            potentieller Spam sind. Er bietet auch Methoden für das Übertragen von Daten als
            bekannter Spam oder als falsch Positiv (ham). Original war es dazu gedacht um für
            Wordpress zu kategorisieren und Spam zu identifizieren, aber es für alle Arten von
            Daten verwendet werden.
        </para>

        <para>
            Akismet benötigt einen <acronym>API</acronym> Schlüssel um verwendet zu werden. Man kann
            einen bekommen indem man sich für einen
            <ulink url="http://wordpress.com/">WordPress.com</ulink> Zugang einschreibt. Man muß
            keinen Blog aktivieren. Nur das Erstellen des Accounts reicht um den
            <acronym>API</acronym> Schlüssel zu erhalten.
        </para>

        <para>
            Akismet erfordert dass alle Anfragen eine <acronym>URL</acronym> zu der
            Ressource enthalten für welche die Daten gefiltert werden. Weil Akismeth's Ursprung
            Wordpress ist, wird diese Ressource die Blog <acronym>URL</acronym> genannt. Dieser Wert
            sollte als zweites Argument an den Konstruktor übergeben werden; aber er kann zu jeder
            Zeit zurückgesetzt werden in dem der <methodname>setBlogUrl()</methodname> Methode
            verwendet wird, oder überschrieben durch die Spezifizierung eines 'blog' Schlüssels in
            den verschiedenen Methodenaufrufen.
        </para>
    </sect2>

    <sect2 id="zend.service.akismet.verifykey">
        <title>Prüfen eines API Schlüssels</title>

        <para>
            <methodname>Zend_Service_Akismet::verifyKey($key)</methodname> wird verwendet um zu
            prüfen ob ein Akismet <acronym>API</acronym> Schlüssel gültig ist. In den meisten
            Fällen, besteht keine Notwendigkeit ihn zu prüfen, aber wenn eine Qualitätssicherung
            durchgeführt werden soll, oder eruiert werden soll ob ein neuerer erhaltener Schlüssel
            aktiv ist, kann das mit dieser Methode gemacht werden.
        </para>

        <programlisting language="php"><![CDATA[
// Instanzieren mit dem API Schlüssel und einer URL zur Anwendung oder
// Ressource die verwendet wird
$akismet = new Zend_Service_Akismet($apiKey,
                                    'http://framework.zend.com/wiki/');
if ($akismet->verifyKey($apiKey) {
    echo "Schlüssel ist gültig.\n";
} else {
    echo "Schlüssel ist ungültig\n";
}
]]></programlisting>

        <para>
            Wenn <methodname>verifyKey()</methodname> ohne Argumente aufgerufen wird, verwendet es
            den <acronym>API</acronym> Schlüssel der im Konstruktor angegeben wurde.
        </para>

        <para>
            <methodname>verifyKey()</methodname> implementiert Akismet's <code>verify-key</code>
            REST Methode.
        </para>
    </sect2>

    <sect2 id="zend.service.akismet.isspam">
        <title>Auf Spam prüfen</title>

        <para>
            <methodname>Zend_Service_Akismet::isSpam($data)</methodname> wird verwendet um zu prüfen
            ob die übergebenen Daten von Akismet als Spam erkannt werden. Es wird ein assoziatives
            Array als Basisargument akzeptiert. Das Array erfordert das die folgenden Schlüssel
            gesetzt werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>user_ip</code>, die IP Adresse des Benutzer der die Daten übermittelt
                    (nicht die eigene IP Adresse, aber die des Benutzers der eigenen Seite).
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>user_agent</code>, der mitgeteilte String des BenutzerAgenten (Browser und
                    Version) oder der Benutzer der die Daten überträgt.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Die folgenden Schlüssel werden im speziellen auch von der <acronym>API</acronym>
            erkannt:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>blog</code>, die komplett qualifizierte <acronym>URL</acronym> zur
                    Ressource oder Anwendung. Wenn nicht angegeben, wird die <acronym>URL</acronym>
                    verwendet die beim Konstruktor angegeben wurde.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>referrer</code>, der Inhalt des HTTP_REFERER Headers
                    zur Zeit der Übertragung. (Beachte die Schreibweise; sie folgt nicht dem Header
                    Namen)
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>permalink</code>, Der Ort des Permalinks vom Eintrag der Daten die
                    übertragen wurden, wenn vorhanden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>comment_type</code>, der Typ von Daten die angegeben wurden. In der
                    <acronym>API</acronym> spezifizierte Werte enthalten 'comment', 'trackback',
                    'pingback', und einen leeren String (''), können aber beliebige Werte sein.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>comment_author</code>, der Name der Person welche die Daten überträgt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>comment_author_email</code>, die Email der Person welche die Daten
                    überträgt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>comment_author_url</code>, die <acronym>URL</acronym> oder Homepage der
                    Person welche die Daten überträgt.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>comment_content</code>, der aktuell übertragene Dateninhalt.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Es können auch beliebige andere Umgebungsvariablen übermittelt werden von denen
            angenommen wird, das Sie bei er Ermittlung helfen ob Daten Spam sind. Akismet empfiehlt
            den Inhalt des kompletten $_SERVER Arrays.
        </para>

        <para>
            Die <methodname>isSpam()</methodname> Methode gibt <constant>TRUE</constant> oder
            <constant>FALSE</constant> zurück, oder wirft eine Exception wenn der
            <acronym>API</acronym> Schlüssel nicht gültig ist.
        </para>

        <example id="zend.service.akismet.isspam.example-1">
            <title>Verwendung von isSpam()</title>

            <programlisting language="php"><![CDATA[
$data = array(
    'user_ip'              => '111.222.111.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT ' .
                              '5.2; en-GB; rv:1.8.1) Gecko/20061010 ' .
                              'Firefox/2.0',
    'comment_type'         => 'contact',
    'comment_author'       => 'John Doe',
    'comment_author_email' => 'nospam@myhaus.net',
    'comment_content'      => "Ich bin kein Spammer, ehrlich!"
);
if ($akismet->isSpam($data)) {
    echo "Sorry, aber wir denken das Du ein Spammer bist.";
} else {
    echo "Willkommen auf unserer Seite!";
}
]]></programlisting>
        </example>

        <para>
            <methodname>isSpam()</methodname> implementiert die <code>comment-check</code> Methode
            der Akismet <acronym>API</acronym>.
        </para>
    </sect2>

    <sect2 id="zend.service.akismet.submitspam">
        <title>Bekannten Spam übertragen</title>

        <para>
            Spam Daten kommen gelegentlich durch den Filter. Wenn in der Begutachtung der
            hereinkommenden Daten Spam erkannt wird, und man das Gefühl hat das er gefunden werden
            sollte, kann er an Akismet übertragen werden um deren Filter zu verbessern.
        </para>

        <para>
            <methodname>Zend_Service_Akismet::submitSpam()</methodname> nimmt das selbe Datenarray
            entgegen wie es der <methodname>isSpam()</methodname> übergeben wird, aber es wird kein
            Wert zurückgegeben. Eine Ausnahme wird geworfen wenn der <acronym>API</acronym>
            Schlüssel ungültig ist.
        </para>

        <example id="zend.service.akismet.submitspam.example-1">
            <title>Verwendung von submitSpam()</title>

            <programlisting language="php"><![CDATA[
$data = array(
    'user_ip'              => '111.222.111.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
                              'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
    'comment_type'         => 'contact',
    'comment_author'       => 'John Doe',
    'comment_author_email' => 'nospam@myhaus.net',
    'comment_content'      => "Ich bin kein Spammer, ehrlich!"
);
$akismet->submitSpam($data));
]]></programlisting>
        </example>

        <para>
            <methodname>submitSpam()</methodname> implementiert die <code>submit-spam</code> Methode
            der Akismet <acronym>API</acronym>.
        </para>
    </sect2>

    <sect2 id="zend.service.akismet.submitham">
        <title>Falsche Positive (Ham) übermitteln</title>

        <para>
            Daten werden genegentlich fehlerhafterweise von Akismet als Spam erkannt. Für diesen
            Fall, sollte ein Log aller Daten behalten werden, indem alle Daten die von Akismet als
            Spam erkannt, geloggt werden und dieses von Zeit zu Zeit durchgesehen. Wenn solche Fülle
            gefunden werden, können die Daten an Akismet als "Ham", oder falsche Positive
            übermittelt werden (Ham ist gut, Spam ist schlecht)
        </para>

        <para>
            <methodname>Zend_Service_Akismet::submitHam()</methodname> nimmt das selbe Datenarray
            entgegen wie <methodname>isSpam()</methodname> oder
            <methodname>submitSpam()</methodname>, und wie bei <methodname>submitSpam()</methodname>
            wird kein Wert zurückgegeben. Eine Ausnahme wird geworfen wenn der verwendete
            <acronym>API</acronym> Schlüssel ungültig ist.
        </para>

        <example id="zend.service.akismet.submitham.example-1">
            <title>Verwenden von submitHam()</title>

            <programlisting language="php"><![CDATA[
$data = array(
    'user_ip'              => '111.222.111.222',
    'user_agent'           => 'Mozilla/5.0 (Windows; U; Windows NT 5.2;' .
                              'en-GB; rv:1.8.1) Gecko/20061010 Firefox/2.0',
    'comment_type'         => 'contact',
    'comment_author'       => 'John Doe',
    'comment_author_email' => 'nospam@myhaus.net',
    'comment_content'      => "I'm not a spammer, honest!"
);
$akismet->submitHam($data));
]]></programlisting>
        </example>

        <para>
            <methodname>submitHam()</methodname> implementiert die <code>submit-ham</code> Methode
            der Akismet <acronym>API</acronym>.
        </para>
    </sect2>

    <sect2 id="zend.service.akismet.accessors">
        <title>Zend-spezifische Methoden</title>

        <para>
            Wärend die Akismet <acronym>API</acronym> nur vier Methoden spezifiziert, hat
            <classname>Zend_Service_Akismet</classname> verschiedene zusätzliche Methoden die für
            das Empfangen und Ändern von internen Eigenschaften verwendet werden können.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getBlogUrl()</methodname> und <methodname>setBlogUrl()</methodname>
                    erlaubt das Empfangen und Ändern der Blog <acronym>URL</acronym> die in den
                    Anfragen verwendet wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getApiKey()</methodname> und <methodname>setApiKey()</methodname>
                    erlauben das Empfangen und Ändern des <acronym>API</acronym> Schlüssels der in
                    Anfragen verwendet wird.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getCharset()</methodname> und <methodname>setCharset()</methodname>
                    erlauben das Empfangen und Ändern des Zeichensatzes der verwendet wird um die
                    Anfrage durchzuführen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getPort()</methodname> und <methodname>setPort()</methodname>
                    erlauben das Empfangen und Ändern des <acronym>TCP</acronym> Ports der verwendet
                    wird um die Anfrage durchzuführen.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getUserAgent()</methodname> und
                    <methodname>setUserAgent()</methodname> erlauben das Empfangen und Ändern des
                    <acronym>HTTP</acronym> Benutzer Agenten der verwendet wird um die Anfrage
                    durchzuführen. Beachte: Das ist nicht der user_agent der in den Daten verwendet
                    wird die in den Service übertragen werden, aber der Wert der im
                    <acronym>HTTP</acronym> User-Agent Header übergeben wird, wenn eine Anfrage an
                    den Service durchgeführt wird.
                </para>

                <para>
                    Der Wert der verwendet wird um den Benutzer Agenten zu setzen sollte die Form
                    <code>ein Benutzer Agent/Version | Akismet/Version</code> haben. Der
                    Standardwert ist <code>Zend Framework/ZF-VERSION | Akismet/1.11</code>, wobei
                    <code>ZF-VERSION</code> die aktuelle Version des Zend Frameworks ist wie in der
                    Konstante <constant>Zend_Framework::VERSION</constant> gespeichert.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>
</sect1>