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 aufeinander folgende 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 FALSE).
Ein Nicht setzen 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($cookieStr, [$refUri,
[$encodeValue]])-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.
Die Methode fromString() akzeptiert die folgenden
Parameter:
-
$cookieStr: Ein Cookie String wie im
HTTP Response Header 'Set-Cookie' oder im
HTTP Request Header 'Cookie' (wird dort benötigt)
dargestellt
-
$refUri: Eine Referenz URI
auf welche die Domain und der Pfad von Cookies gesetzt werden.
(Optional wird standardmäßig dieser Wert von $cookieStr geparst)
-
$encodeValue: Ob der Wert über urldecode
übergeben werden soll.Hat auch Einfluss auf der Verhalten des
Cookies wenn es in einen Cookie String zurück konvertiert wird.
(Optional ist er standardmäßig true)
Example #1 Instanzieren eines Zend_Http_Cookie-Objekts
// Zuerst nutzen wir den Konstruktor. Der Cookie wird in zwei Stunden ablaufen
'foo',
'bar',
'.example.com''/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.
'foo=bar; domain=.example.com; ' .
'path=/path; secure');
// Wenn die Domain des Cookies nicht gesetzt ist, muss man ihn selbst angeben.
'foo=bar; secure;',
'http://www.example.com/path');
Note:
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:
Example #2 Transformation eines Zend_Http_Cookie-Objekts zu einem String
// Erstellt einen neuen Cookie
'foo',
'two words',
'.example.com''/path');
// Gibt 'foo=two+words;' aus
// Bezweckt dasselbe
// Ab PHP 5.2 funktioniert auch diese Variante
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:
-
getName(): Gibt den Namen des Cookies zurück
-
getValue(): Gibt den wirklichen, also nicht
kodierten, Inhalt zurück
-
getDomain(): Gibt die Domain des Cookies zurück
-
getPath(): Gibt den Pfad des Cookies zurück; dessen
Standardwert ist '/'
-
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:
-
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.
-
isExpired(int $time = null): Überprüft, ob der
Cookie bereits abgelaufen ist. Wenn der Cookie keine Ablaufzeit besitzt,
wird diese Methode immer FALSE zurückgegeben. Wenn
$time übergeben wurde, wird der aktuelle Zeitstempel überschrieben und der
übergebene Zeitstempel zur Überprüfung genutzt.
-
isSessionCookie(): Überprüft, ob der Cookie ein
"Session-Cookie" ist, der keine Ablaufzeit besitzt und erst abläuft, wenn
die Session beendet wird.
Example #3 Nutzen der getter-Methoden von Zend_Http_Cookie
// Zuerst wird der Cookie erstellt
'foo=two+words; ' +
'domain=.example.com; ' +
'path=/somedir; ' +
'secure; ' +
'expires=Wednesday, 28-Feb-05 20:41:22 UTC'// Gibt 'foo' aus
// Gibt 'two words' aus
// Gibt '.example.com' aus
// Gibt '/' aus
'Y-m-d'// Gibt '2005-02-28' aus
'Ja' : 'Nein');
// Gibt 'Ja' aus
'2005-01-01') ? 'Ja' : 'Nein');
// Gibt 'Nein' aus
'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:
Zend_Http_Cookie->match(mixed $uri, [boolean $matchSessionCookies,
[int $now]]);
-
$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.
-
$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.
-
$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.
Example #4 Zutreffen von Cookies
// Erstellen eines Cookie Objekts - zuerst ein sicherer Cookie ohne Ablaufzeit
'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'// 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
'foo=two+words; ' +
'domain=www.example.com; ' +
'expires=''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/'// 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 in
diesem Abschnitt.
|
|