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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15617 -->
<!-- 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 language="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 language="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 language="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 language="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>, und
            <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:
-->