repo_zf1/documentation/manual/de/module_specs/Zend_Http_Cookie-Handling.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 14978 -->
<!-- Reviewed: no -->
<sect1 id="zend.http.cookies">
    <title>Zend_Http_Cookie und Zend_Http_CookieJar</title>

    <sect2 id="zend.http.cookies.introduction">
        <title>Einführung</title>
        <para>
            Wie erwartet ist Zend_Http_Cookie eine Klasse, die einen HTTP-Cookie
            darstellt. Sie stellt Methoden zum Verarbeiten von HTTP-Antwort-Strings,
            Sammeln von Cookies und dem einfachen Zugriff auf deren Eigenschaften zur
            Verfügung. So ist es auch möglich verschiedene Zustände eines Cookies
            zu überprüfen, z.B. den Anfrage-URL, die Ablaufzeit, das Vorliegen
            einer sicheren Verbindung, etc.
        </para>
        <para>
            Zend_Http_CookieJar ist ein Objekt, das normalerweise von der Klasse
            Zend_Http_Client genutzt wird und einen Satz von
            Zend_Http_Cookie Objekten beinhaltet. Wenn die Klassen miteinander
            verbunden sind, werden alle ein- und ausgehenden Cookies der
            HTTP-Anfragen und -Antworten im CookieJar Objekt gespeichert. Bei
            einer neuen Anfrage seitens des Clients wird nach allen Cookies,
            die auf diese Anfrage zutreffen, gesucht. Diese werden automatisch
            zum Anfrage-Header hinzugefügt, was besonders nützlich ist, wenn man
            eine Benutzersession über aufeinanderfolgende HTTP-Anfragen beibehalten
            muss; die Session-ID wird automatisch gesendet, wenn es notwendig ist.
            Ferner ist es möglich, Zend_Http_CookieJar Objekte zu serialisieren und,
            wenn nötig, in $_SESSION zu speichern.
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.instantiating">
        <title>Instanzieren von Zend_Http_Cookie Objekten</title>
        <para>
            Es gibt zwei Möglichkeiten ein Cookie Objekt zu erstellen:
            <itemizedlist>
                <listitem>
                    <para>
                    Mithilfe des Konstruktors und der folgenden Syntax:
                    <code>new Zend_Http_Cookie(string $name, string $value, string $domain, [int $expires, [string $path, [boolean $secure]]]);</code>
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                            <code>$name</code>: Name des Cookies (notwendig)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$value</code>: Inhalt des Cookies (notwendig)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$domain</code>: Die Domain des Cookies (z.B. '.example.com') (notwendig)
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$expires</code>: Ablaufzeit des Cookies als UNIX Zeitstempel (optional,
                            standardmäßig null).
                            Ein Nichtsetzen führt zu einer Behandlung als 'Session-Cookie', das keine Ablaufzeit
                            enthält.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$path</code>: Pfad des Cookies, z.B. '/foo/bar/' (optional, standardmäßig '/')
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$secure</code>: Boolean, ob der Cookie nur über sichere Verbindungen (HTTPS) gesendet
                            werden darf  (optional, standardmäßig boolean FALSE)
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
                <listitem>
                    <para>
                    Durch das Aufrufen der statischen fromString()-Methode mit einem Cookie-String, wie er
                    unter 'Set-Cookie' in einer HTTP-Antwort und 'Cookie' in einer -Anfrage zu finden ist.
                    In diesem Fall muss der Cookie-Inhalt bereits kodiert sein. Falls der Cookie-String keinen
                    'domain'-Teil enthält, muss man selbst einen Referenz-URI angeben, aus dem die Domain und
                    der Pfad des Cookies bestimmt wird.
                    </para>
                </listitem>
            </itemizedlist>
            <example id="zend.http.cookies.cookie.instantiating.example-1">
               <title>Instanzieren eines Zend_Http_Cookie-Objekts</title>
               <programlisting role="php"><![CDATA[
// Zuerst nutzen wir den Konstruktor. Der Cookie wird in zwei Stunden ablaufen
$cookie = new Zend_Http_Cookie('foo',
                               'bar',
                               '.example.com',
                               time() + 7200,
                               '/path');

// Man kann auch den HTTP-Antwort 'Set-Cookie'-header dafür nutzen.
// Dieser Cookie ist ähnlich zum vorangegangenen, allerdings wird
// er nicht ablaufen und nur über sichere Verbindungen gesendet.
$cookie = Zend_Http_Cookie::fromString('foo=bar; domain=.example.com; ' .
                                       'path=/path; secure');

// Wenn die Domain des Cookies nicht gesetzt ist, muss man ihn selbst angeben.
$cookie = Zend_Http_Cookie::fromString('foo=bar; secure;',
                                       'http://www.example.com/path');
]]>
                </programlisting>
            </example>
            <note>
                <para>
                Beim Instanzieren eines Cookie Objekts mit der Zend_Http_Cookie::fromString()-Methode
                wird erwartet, dass der Cookie-Inhalt URL-kodiert ist, wie es bei Cookie-Strings sein
                sollte. Allerdings wird angenommen, dass der Inhalt bei Verwendung des Konstruktors
                in seiner eigentlichen Form, d.h. nicht URL-kodiert, übergeben wird.
                </para>
            </note>
        </para>
        <para>
            Ein Cookie Objekt kann durch die magische __toString()-Methode zurück in einen String
            umgewandelt werden. Diese Methode erstellt einen HTTP-Anfrage "Cookie"-Header String, der den
            Namen sowie den Inhalt des Cookies enthält und durch ein Semikolon (';') abgeschlossen ist.
            Der Inhalt wird URL-kodiert, wie es für einen Cookie-Header vorgeschrieben ist:
            <example id="zend.http.cookies.cookie.instantiating.example-2">
               <title>Transformation eines Zend_Http_Cookie-Objekts zu einem String</title>
               <programlisting role="php"><![CDATA[
// Erstellt einen neuen Cookie
$cookie = new Zend_Http_Cookie('foo',
                               'two words',
                               '.example.com',
                               time() + 7200,
                               '/path');

// Gibt 'foo=two+words;' aus
echo $cookie->__toString();

// Bezweckt dasselbe
echo (string) $cookie;

// Ab PHP 5.2 funktioniert auch diese Variante
echo $cookie;
]]>
                </programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.accessors">
        <title>Zend_Http_Cookie getter-Methoden</title>
        <para>
            Sobald ein Zend_Http_Cookie instanziert wurde, stellt es diverse getter-Methoden zur
            Verfügung, die es einem ermöglichen, auf die verschiedenen Eigenschaften des HTTP-Cookies
            zuzugreifen:
            <itemizedlist>
                <listitem>
                    <para>
                    <code>string getName()</code>: Gibt den Namen des Cookies zurück
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>string getValue()</code>: Gibt den wirklichen, also nicht kodierten, Inhalt zurück
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>string getDomain()</code>: Gibt die Domain des Cookies zurück
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>string getPath()</code>: Gibt den Pfad des Cookies zurück; dessen Standardwert ist '/'
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>int getExpiryTime()</code>: Gibt die Ablaufzeit des Cookies als UNIX-Timestamp zurück.
                    Falls der Cookie keine Ablaufzeit besitzt, wird NULL zurückgegeben.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            Zusätzlich gibt es einige boolesche tester-Methoden:
            <itemizedlist>
                <listitem>
                    <para>
                    <code>boolean isSecure()</code>: Gibt zurück, ob der Cookie nur über sichere Verbindungen
                    gesendet werden kann. Wenn true zurückgegeben wird, wird der Cookie also nur über HTTPS
                    versendet.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>boolean isExpired(int $time = null)</code>: Überprüft, ob der Cookie bereits abgelaufen ist.
                    Wenn der Cookie keine Ablaufzeit besitzt, wird diese Methode immer true zurückgegeben. Wenn
                    $time übergeben wurde, wird der aktuelle Zeitstempel überschrieben und der übergebene Zeitstempel
                    zur Überprüfung genutzt.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>boolean isSessionCookie()</code>: Überprüft, ob der Cookie ein "Session-Cookie" ist, der
                    keine Ablaufzeit besitzt und erst abläuft, wenn die Session beendet wird.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            <example id="zend.http.cookies.cookie.accessors.example-1">
                <title>Nutzen der getter-Methoden von Zend_Http_Cookie</title>
                <programlisting role="php"><![CDATA[
// Zuerst wird der Cookie erstellt
$cookie = Zend_Http_Cookie::fromString(
    'foo=two+words; ' +
    'domain=.example.com; ' +
    'path=/somedir; ' +
    'secure; ' +
    'expires=Wednesday, 28-Feb-05 20:41:22 UTC');

echo $cookie->getName();   // Gibt 'foo' aus
echo $cookie->getValue();  // Gibt 'two words' aus
echo $cookie->getDomain(); // Gibt '.example.com' aus
echo $cookie->getPath();   // Gibt '/' aus

echo date('Y-m-d', $cookie->getExpiryTime());
// Gibt '2005-02-28' aus

echo ($cookie->isExpired() ? 'Ja' : 'Nein');
// Gibt 'Ja' aus

echo ($cookie->isExpired(strtotime('2005-01-01') ? 'Ja' : 'Nein');
// Gibt 'Nein' aus

echo ($cookie->isSessionCookie() ? 'Ja' : 'Nein');
// Gibt 'Nein' aus
]]>
                </programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookie.matching">
        <title>Zend_Http_Cookie: Überprüfen von Szenarien</title>
        <para>
            Die einzige wirkliche Logik in einem Zend_Http_Cookie-Objekt befindet sich in der match()-Methode.
            Sie wird genutzt um zu Überprüfen, ob ein Cookie auf eine HTTP-Anfrage zutrifft, um
            zu entscheiden, ob der Cookie in der Anfrage gesendet werden soll. Die Methode hat
            folgende Syntax und Parameter:
            <code>boolean Zend_Http_Cookie->match(mixed $uri, [boolean $matchSessionCookies, [int $now]]);</code>
            <itemizedlist>
                <listitem>
                    <para>
                    <code>mixed $uri</code>: Ein zu überprüfendes Zend_Uri_Http-Objekt mit einer Domain und einem Pfad.
                    Wahlweise kann stattdessen jedoch auch ein String, der einen validen HTTP-URL darstellt, übergeben
                    werden. Der Cookie ist zutreffend, wenn das URL-Schema (HTTP oder HTTPS), die Domain sowie
                    der Pfad passen.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>boolean $matchSessionCookies</code>: Gibt an, ob Session-Cookies zutreffen sollen.
                    Standardmäßig ist dieser Parameter true. Wenn false stattdessen übergeben wird, werden
                    Cookies ohne Ablaufzeit nie zutreffen.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <code>int $now</code>: Ablaufzeit (in Form eines UNIX-Zeitstempels) auf welche der Cookie
                    überprüft wird. Wenn sie nicht angegeben wird, wird die gegenwärtige Zeit genutzt.
                    </para>
                </listitem>
            </itemizedlist>
            <example id="zend.http.cookies.cookie.matching.example-1">
                <title>Zutreffen von Cookies</title>
                <programlisting role="php"><![CDATA[
// Erstellen eines Cookie Objekts - zuerst ein sicherer Cookie ohne Ablaufzeit
$cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
                                       'domain=.example.com; ' +
                                       'path=/somedir; ' +
                                       'secure;');

$cookie->match('https://www.example.com/somedir/foo.php');
// Gibt true zurück

$cookie->match('http://www.example.com/somedir/foo.php');
// Gibt false zurück, da die Verbindung nicht sicher ist

$cookie->match('https://otherexample.com/somedir/foo.php');
// Gibt false zurück, da die Domain falsch ist

$cookie->match('https://example.com/foo.php');
// Gibt false zurück, da der Pfad falsch ist

$cookie->match('https://www.example.com/somedir/foo.php', false);
// Gibt false zurück, da keine Session-Cookies akzeptiert werden

$cookie->match('https://sub.domain.example.com/somedir/otherdir/foo.php');
// Gibt true zurück

// Erstellen eines anderen Cookie-Objekts - diesmal unsicher und
// einer Ablaufzeit die zwei Stunden in der Zukunft liegt
$cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
                                       'domain=www.example.com; ' +
                                       'expires='
                                       . date(DATE_COOKIE, time() + 7200));

$cookie->match('http://www.example.com/');
// Gibt true zurück

$cookie->match('https://www.example.com/');
// Gibt true zurück, da unsichere Cookies genauso gut über sichere
// Verbindungen übertragen werden können

$cookie->match('http://subdomain.example.com/');
// Gibt false zurück, da die Domain unzutreffend ist

$cookie->match('http://www.example.com/', true, time() + (3 * 3600));
// Gibt false zurück, da die Ablaufzeit drei Stunden in der Zukunft
// liegt
]]>
                </programlisting>
            </example>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar">
        <title>Die Zend_Http_CookieJar Klasse: Instanzierung</title>
        <para>
            In den meisten Fällen ist es nicht notwendig, ein Zend_Http_CookieJar Objekt
            direkt zu erstellen. Wenn man ein neues CookieJar zum Zend_Http_Client Objekts
            hinzufügen will, muss man lediglich die Methode Zend_Http_Client->setCookieJar(
            aufrufen, die ein neues und leeres CookieJar zum Client hinzufügt. Später kann
            man dieses CookieJar via Zend_Http_Client->getCookieJar() holen.
        </para>
        <para>
            Wenn dennoch ein CookieJar Objekt manuell erstellen werden soll, kann man dies
            direkt durch "new Zend_Http_CookieJar()" erreichen - der Konstruktor benötigt
            keine Parameter. Ein anderer Weg zum Instanzieren eines CookieJar Objekts ist
            es, die statische Methode Zend_Http_CookieJar::fromResponse() zu nutzen. Diese
            Methode benötigt zwei Parameter: ein Zend_Http_Response Objekt und einen
            Referenz_URI, entweder in Form eines Strings oder eines Zend_Uri_Http Objekts.
            Es wird ein Zend_Http_CookieJar Objekt zurückgegeben, das bereits die Cookies,
            die durch die HTTP-Antwort gesetzt wurden, enthält. Der Referenz-URI wird
            genutzt um die Domain und den Pfad des Cookies zu setzen, sofern sie nicht
            in den Set-Cookie-Headern definiert wurden.
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar.adding_cookies">
        <title>Hinzufügen von Cookies zu einem Zend_Http_CookieJar Objekt</title>
        <para>
            Normalerweise werden die, durch HTTP-Antworten gesetzen, Cookies vom Zend_Http_Client Objekt
            automatisch zu dessen CookieJar hinzugefügt. Wenn man es wünscht, kann man Cookies
            auch manuell zum CookieJar hinzufügen, was durch Nutzen zweier Methoden
            erreicht werden kann:
            <itemizedlist>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->addCookie($cookie[, $ref_uri])</classname>: Hinzufügen eines
                    einzelnen Cookies zum CookieJar. $cookie kann entweder ein Zend_Http_Cookie-Objekt
                    oder ein String, der automatisch zu einem Cookie Objekt transformiert wird,
                    sein. Wenn ein String übergeben wird, sollte man jedoch zusätzlich immer $ref_uri
                    übergeben, da dieser einen Referenz-URI darstellt - in Form eines Strings oder eines
                    Zend_Uri_Http Objekts - dessen Werte als Standard für die Domain und den Pfad des
                    Cookies genutzt werden.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->addCookiesFromResponse($response, $ref_uri)</classname>:
                    Fügt alle Cookies zum CookieJar hinzu, die in einer einzelnen HTTP-Antwort gesetzt
                    wurden. Es wird erwartet, dass $response ein Zend_Http_Response Objekt mit
                    Set-Cookie-Headern ist. $ref_uri ist ein Anfrage-URI in Form eines Strings
                    oder eines Zend_Uri_Http-Objekts dessen Inhalt die Standarddomain und den -pfad
                    des Cookies bestimmt.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.http.cookies.cookiejar.getting_cookies">
        <title>Abrufen der Cookies von einem Zend_Http_CookieJar-Objekts</title>
        <para>
            Wie beim Hinzufügen von Cookies ist es normalerweise nicht notwendig,
            die Cookies manuell von einem CookieJar Objekt zu holen. Das Zend_Http_Client Objekt
            holt automatisch alle benötigten Cookies für eine HTTP-Anfrage. Allerdings
            gibt es drei Methoden die Cookies aus einem CookieJar zu holen: <code>getCookie()</code>,
            <code>getAllCookies()</code>, and <code>getMatchingCookies()</code>. Zusätzlich erhält man
            alle Zend_Http_Cookie Objekte von CookieJar wenn man durch Ihn iteriert.
        </para>
        <para>
            Es ist wichtig anzumerken, dass jede dieser Methoden einen speziellen
            Parameter verlangt, der den Rückgabetyp der Methode festlegt. Dieser
            Parameter kann drei verschiedene Werte annehmen:
            <itemizedlist>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar::COOKIE_OBJECT</classname>: Gibt ein
                    Zend_Http_Cookie Objekt zurück. Wenn diese Methode mehr als
                    einen Cookie zurückgeben sollte, wird stattdessen ein Array aus Objekten
                    zurückgegeben.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar::COOKIE_STRING_ARRAY</classname>: Gibt Cookies
                    als Strings - im Format "foo=bar" - zurück, welche passend für das
                    Senden im "Cookie"-Header einer HTTP-Anfrage sind. Wenn mehr als
                    ein Cookie zurückgegeben werden sollte, wird stattdessen ein Array
                    solcher Strings zurückgegeben.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar::COOKIE_STRING_CONCAT</classname>: Ähnlich zu
                    COOKIE_STRING_ARRAY; allerdings gibt diese Methode, falls mehr als
                    ein Cookie zurückgegeben wird, einen einzelnen, langen String zurück,
                    der die Cookies anhand eines Semikolons (;) trennt. Dieses Prozedere
                    ist besonders hilfreich, wenn man alle zutreffenden Cookies in einem
                    einzelnen "Cookie"-Header einer HTTP-Anfrage zurückgeben will.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            Die Struktur der unterschiedlichen Cookie-Abrufmethoden wird unterhalb beschrieben:
            <itemizedlist>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getCookie($uri, $cookie_name[, $ret_as])</classname>:
                    Gibt einen einzelnen Cookie von dem CookieJar zurück, dessen URI (Domain und
                    Pfad) und Name zu den Parametern passen. $uri ist entweder ein String oder
                    ein Zend_Http_Uri Objekt, die den URI darstellen. $cookie_name ist ein String
                    zum Identifizieren des Cookie-Namens. $ret_as ist ein optionaler Parameter, der
                    angibt, von welchem Typ der zurückgegebene Wert ist. Der Standardwert ist
                    COOKIE_OBJECT.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getAllCookies($ret_as)</classname>: Holt alle Cookies
                    aus dem CookieJar. $ret_as gibt den Rückgabetyp - wie oben bereits beschrieben - an.
                    Wenn er nicht angegeben wird, nimmt er COOKIE_OBJECT an.
                    </para>
                </listitem>
                <listitem>
                    <para>
                    <classname>Zend_Http_CookieJar->getMatchingCookies($uri[, $matchSessionCookies[, $ret_as[, $now]]])</classname>:
                    Gibt alle Cookies vom CookieJar zurück, die mit der Ablaufzeit und dem URI übereinstimmen.
                    <itemizedlist>
                        <listitem>
                            <para>
                            <code>$uri</code> ist entweder ein Zend_Uri_Http Objekt oder ein String, der den
                            Verbindungstyp (sicher oder unsicher), die Domain und den Pfad angibt.
                            Nach diesen Informationen wird im CookieJar gesucht.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$matchSessionCookies</code> ist ein boolescher Ausdruck, der festlegt, ob nach
                            Session-Cookies gesucht werden soll. Session-Cookies sind Cookies, die keine Ablaufzeit
                            enthalten. Standardmäßig ist dieser Wert true.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$ret_as</code> gibt den Rückgabetyp - wie oben beschrieben - an. Wenn
                            keiner angegeben wird, wird COOKIE_OBJECT angenommen.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                            <code>$now</code> ist ein Integer der einen UNIX-Zeitstempel darstellt. Cookies,
                            die vor der angegeben Zeit ablaufen, werden nicht zurückgegeben. Wenn dieser Parameter
                            nicht angegeben wird, wird stattdessen die aktuelle Zeit gewählt.
                            </para>
                        </listitem>
                    </itemizedlist>
                    Mehr über das Zutreffen von Cookies gibt es hier:
                    <xref linkend="zend.http.cookies.cookie.matching" />.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->