# Zend_Http_Cookie und Zend_Http_CookieJar

## Einführung

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.

`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. Die Idee ist das wenn ein `Zend_Http_CookieJar` an ein `Zend_Http_Client` Objekt angehängt wird, alle ein- und ausgehenden Cookies der HTTP Anfragen und -Antworten im CookieJar Objekt gespeichert werden. 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.

## Instanzieren von Zend_Http_Cookie Objekten

Es gibt zwei Möglichkeiten ein Cookie Objekt zu erstellen:

- Mithilfe des Konstruktors und der folgenden Syntax: `new `Zend_Http_Cookie`(string $name, string $value, string $domain, [int $expires, [string $path, [boolean $secure]]]);`

  - `$name`: Name des Cookies (notwendig)

  - `$value`: Inhalt des Cookies (notwendig)

  - `$domain`: Die Domain des Cookies (z.B. '.example.com') (notwendig)

  - `$expires`: 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.

  - `$path`: Pfad des Cookies, z.B. '/foo/bar/' (optional, standardmäßig '/')

  - `$secure`: Boolean, ob der Cookie nur über sichere Verbindungen (HTTPS) gesendet werden darf (optional, standardmäßig boolean FALSE)

- Durch das Aufrufen der statischen fromString()-Methode mit einem Cookie-String, wie er unter 'Set-Cookie' in einer HTTP Antwort und 'Cookie' in einer HTTP 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.

### Instanzieren eines Zend_Http_Cookie-Objekts

    // 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');

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.

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:

### Transformation eines Zend_Http_Cookie-Objekts zu einem String

    // 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;

## Zend_Http_Cookie getter-Methoden

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:

- `string getName()`: Gibt den Namen des Cookies zurück

- `string getValue()`: Gibt den wirklichen, also nicht kodierten, Inhalt zurück

- `string getDomain()`: Gibt die Domain des Cookies zurück

- `string getPath()`: Gibt den Pfad des Cookies zurück; dessen Standardwert ist '/'

- `int getExpiryTime()`: Gibt die Ablaufzeit des Cookies als UNIX-Timestamp zurück. Falls der Cookie keine Ablaufzeit besitzt, wird NULL zurückgegeben.

Zusätzlich gibt es einige boolesche tester-Methoden:

- `boolean isSecure()`: 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.

- `boolean isExpired(int $time = null)`: Ü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.

- `boolean isSessionCookie()`: Überprüft, ob der Cookie ein "Session-Cookie" ist, der keine Ablaufzeit besitzt und erst abläuft, wenn die Session beendet wird.

### Nutzen der getter-Methoden von Zend_Http_Cookie

    // 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

## Zend_Http_Cookie: Überprüfen von Szenarien

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: `boolean Zend_Http_Cookie->match(mixed $uri, [boolean $matchSessionCookies, [int $now]]);`

- `mixed $uri`: 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.

- `boolean $matchSessionCookies`: Gibt an, ob Session-Cookies zutreffen sollen. Standardmäßig ist dieser Parameter true. Wenn false stattdessen übergeben wird, werden Cookies ohne Ablaufzeit nie zutreffen.

- `int $now`: Ablaufzeit (in Form eines UNIX-Zeitstempels) auf welche der Cookie überprüft wird. Wenn sie nicht angegeben wird, wird die gegenwärtige Zeit genutzt.

### Zutreffen von Cookies

    // 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

## Die Zend_Http_CookieJar Klasse: Instanzierung

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.

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.

## Hinzufügen von Cookies zu einem Zend_Http_CookieJar Objekt

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:

- `Zend_Http_CookieJar->addCookie($cookie[, $ref_uri])`: 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.

- `Zend_Http_CookieJar->addCookiesFromResponse($response, $ref_uri)`: 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.

## Abrufen der Cookies von einem Zend_Http_CookieJar-Objekts

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: `getCookie()`, `getAllCookies()`, und `getMatchingCookies()`. Zusätzlich erhält man alle `Zend_Http_Cookie` Objekte von CookieJar wenn man durch Ihn iteriert.

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:

- `Zend_Http_CookieJar::COOKIE_OBJECT`: 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.

- `Zend_Http_CookieJar::COOKIE_STRING_ARRAY`: Gibt Cookies als Strings - im Format "foo=bar" - zurück, welche passend für das Senden im "Cookie"-Header einer HTTPAnfrage sind. Wenn mehr als ein Cookie zurückgegeben werden sollte, wird stattdessen ein Array solcher Strings zurückgegeben.

- `Zend_Http_CookieJar::COOKIE_STRING_CONCAT`: Ä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.

Die Struktur der unterschiedlichen Cookie-Abrufmethoden wird unterhalb beschrieben:

- `Zend_Http_CookieJar->getCookie($uri, $cookie_name[, $ret_as])`: 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.

- `Zend_Http_CookieJar->getAllCookies($ret_as)`: 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.

- `Zend_Http_CookieJar->getMatchingCookies($uri[, $matchSessionCookies[, $ret_as[, $now]]])`: Gibt alle Cookies vom CookieJar zurück, die mit der Ablaufzeit und dem URI übereinstimmen.

  - `$uri` 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.

  - `$matchSessionCookies` 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.

  - `$ret_as` gibt den Rückgabetyp - wie oben beschrieben - an. Wenn keiner angegeben wird, wird COOKIE_OBJECT angenommen.

  - `$now` 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.

  Mehr über das Zutreffen von Cookies gibt es hier: .