documentation/manual/en/module_specs/Zend_Http_Cookie-Handling.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.http.cookies">
   4     <title>Zend_Http_Cookie and Zend_Http_CookieJar</title>
   5
   6     <sect2 id="zend.http.cookies.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Http_Cookie</classname>, as expected, is a class that represents an
  11             <acronym>HTTP</acronym> cookie. It provides methods for parsing <acronym>HTTP</acronym>
  12             response strings, collecting cookies, and easily accessing their properties. It also
  13             allows checking if a cookie matches against a specific scenario, IE
  14             a request <acronym>URL</acronym>, expiration time, secure connection, etc.
  15         </para>
  16
  17         <para>
  18             <classname>Zend_Http_CookieJar</classname> is an object usually used by
  19             <classname>Zend_Http_Client</classname> to hold a set of
  20             <classname>Zend_Http_Cookie</classname> objects. The idea is that if a
  21             <classname>Zend_Http_CookieJar</classname> object is attached to a
  22             <classname>Zend_Http_Client</classname> object, all cookies going from and into the
  23             client through <acronym>HTTP</acronym> requests and responses will be stored by the
  24             CookieJar object. Then, when the client will send another request, it will first ask the
  25             CookieJar object for all cookies matching the request. These will be added to the
  26             request headers automatically. This is highly useful in cases where you need to
  27             maintain a user session over consecutive <acronym>HTTP</acronym> requests, automatically
  28             sending the session ID cookies when required. Additionally, the
  29             <classname>Zend_Http_CookieJar</classname> object can be serialized and stored in
  30             $_SESSION when needed.
  31         </para>
  32     </sect2>
  33
  34     <sect2 id="zend.http.cookies.cookie.instantiating">
  35         <title>Instantiating Zend_Http_Cookie Objects</title>
  36
  37         <para>
  38             Instantiating a Cookie object can be done in two ways:
  39
  40             <itemizedlist>
  41                 <listitem>
  42                     <para>
  43                         Through the constructor, using the following syntax:
  44                         <code>new <classname>Zend_Http_Cookie</classname>(string $name, string
  45                             $value, string $domain, [int $expires, [string $path, [boolean
  46                             $secure]]]);</code>
  47                     </para>
  48
  49                     <itemizedlist>
  50                         <listitem>
  51                             <para>
  52                                 <varname>$name</varname>: The name of the cookie (eg. 'PHPSESSID')
  53                                 (required)
  54                             </para>
  55                         </listitem>
  56
  57                         <listitem>
  58                             <para>
  59                                 <varname>$value</varname>: The value of the cookie (required)
  60                             </para>
  61                         </listitem>
  62
  63                         <listitem>
  64                             <para>
  65                                 <varname>$domain</varname>: The cookie's domain (eg. '.example.com')
  66                                 (required)
  67                             </para>
  68                         </listitem>
  69
  70                         <listitem>
  71                             <para>
  72                                 <varname>$expires</varname>: Cookie expiration time, as UNIX time
  73                                 stamp (optional, defaults to <constant>NULL</constant>). If not set,
  74                                 cookie will be treated as a 'session cookie' with no expiration
  75                                 time.
  76                             </para>
  77                         </listitem>
  78
  79                         <listitem>
  80                             <para>
  81                                 <varname>$path</varname>: Cookie path, eg. '/foo/bar/' (optional,
  82                                 defaults to '/')
  83                             </para>
  84                         </listitem>
  85
  86                         <listitem>
  87                             <para>
  88                                 <varname>$secure</varname>: Boolean, Whether the cookie is to be
  89                                 sent over secure (HTTPS) connections only (optional, defaults to
  90                                 boolean <constant>FALSE</constant>)
  91                             </para>
  92                         </listitem>
  93                     </itemizedlist>
  94                 </listitem>
  95
  96                 <listitem>
  97                     <para>
  98                         By calling the fromString($cookieStr, [$refUri, [$encodeValue]]) static
  99                         method, with a cookie string as represented in the 'Set-Cookie
 100                        ' <acronym>HTTP</acronym> response header or 'Cookie' <acronym>HTTP</acronym>
 101                        request header. In this case, the cookie value must already be encoded. When
 102                        the cookie string does not contain a 'domain' part, you must provide a
 103                        reference <acronym>URI</acronym> according to which the cookie's domain and
 104                        path will be set.
 105                     </para>
 106
 107                     <para>
 108                         The <code>fromString</code> method accepts the following parameters:
 109                     </para>
 110
 111                     <itemizedlist>
 112                         <listitem>
 113                             <para>
 114                                 <varname>$cookieStr</varname>: a cookie string as represented in the
 115                                'Set-Cookie' <acronym>HTTP</acronym> response header or 'Cookie'
 116                                <acronym>HTTP</acronym> request header (required)
 117                             </para>
 118                         </listitem>
 119
 120                         <listitem>
 121                             <para>
 122                                 <varname>$refUri</varname>: a reference <acronym>URI</acronym>
 123                                 according to which the cookie's domain and path will be set.
 124                                 (optional, defaults to parsing the value from the $cookieStr)
 125                             </para>
 126                         </listitem>
 127
 128                         <listitem>
 129                             <para>
 130                                 <varname>$encodeValue</varname>: If the value should be passed
 131                                 through urldecode. Also effects the cookie's behavior when being
 132                                 converted back to a cookie string. (optional, defaults to true)
 133                             </para>
 134                         </listitem>
 135                     </itemizedlist>
 136                 </listitem>
 137             </itemizedlist>
 138
 139             <example id="zend.http.cookies.cookie.instantiating.example-1">
 140                <title>Instantiating a Zend_Http_Cookie object</title>
 141
 142                <programlisting language="php"><![CDATA[
 143 // First, using the constructor. This cookie will expire in 2 hours
 144 $cookie = new Zend_Http_Cookie('foo',
 145                                'bar',
 146                                '.example.com',
 147                                time() + 7200,
 148                                '/path');
 149
 150 // You can also take the HTTP response Set-Cookie header and use it.
 151 // This cookie is similar to the previous one, only it will not expire, and
 152 // will only be sent over secure connections
 153 $cookie = Zend_Http_Cookie::fromString('foo=bar; domain=.example.com; ' .
 154                                        'path=/path; secure');
 155
 156 // If the cookie's domain is not set, you have to manually specify it
 157 $cookie = Zend_Http_Cookie::fromString('foo=bar; secure;',
 158                                        'http://www.example.com/path');
 159 ]]></programlisting>
 160             </example>
 161
 162             <note>
 163                 <para>
 164                     When instantiating a cookie object using the
 165                     <classname>Zend_Http_Cookie</classname>::fromString() method, the cookie value
 166                     is expected to be <acronym>URL</acronym> encoded, as cookie strings should be.
 167                     However, when using the constructor, the cookie value string is expected to be
 168                     the real, decoded value.
 169                 </para>
 170             </note>
 171         </para>
 172
 173         <para>
 174             A cookie object can be transferred back into a string, using the __toString() magic
 175             method. This method will produce a <acronym>HTTP</acronym> request "Cookie" header
 176             string, showing the cookie's name and value, and terminated by a semicolon (';').
 177             The value will be URL encoded, as expected in a Cookie header:
 178             <example id="zend.http.cookies.cookie.instantiating.example-2">
 179                <title>Stringifying a Zend_Http_Cookie object</title>
 180
 181                <programlisting language="php"><![CDATA[
 182 // Create a new cookie
 183 $cookie = new Zend_Http_Cookie('foo',
 184                                'two words',
 185                                '.example.com',
 186                                time() + 7200,
 187                                '/path');
 188
 189 // Will print out 'foo=two+words;' :
 190 echo $cookie->__toString();
 191
 192 // This is actually the same:
 193 echo (string) $cookie;
 194
 195 // In PHP 5.2 and higher, this also works:
 196 echo $cookie;
 197 ]]></programlisting>
 198             </example>
 199         </para>
 200     </sect2>
 201
 202     <sect2 id="zend.http.cookies.cookie.accessors">
 203         <title>Zend_Http_Cookie getter methods</title>
 204
 205         <para>
 206             Once a <classname>Zend_Http_Cookie</classname> object is instantiated, it provides
 207             several getter methods to get the different properties of the <acronym>HTTP</acronym>
 208             cookie:
 209
 210             <itemizedlist>
 211                 <listitem>
 212                     <para>
 213                         <code>string getName()</code>: Get the name of the cookie
 214                     </para>
 215                 </listitem>
 216
 217                 <listitem>
 218                     <para>
 219                         <code>string getValue()</code>: Get the real, decoded value of the cookie
 220                     </para>
 221                 </listitem>
 222
 223                 <listitem>
 224                     <para>
 225                         <code>string getDomain()</code>: Get the cookie's domain
 226                     </para>
 227                 </listitem>
 228
 229                 <listitem>
 230                     <para>
 231                         <code>string getPath()</code>: Get the cookie's path, which defaults to '/'
 232                     </para>
 233                 </listitem>
 234
 235                 <listitem>
 236                     <para>
 237                         <code>int getExpiryTime()</code>: Get the cookie's expiration time, as UNIX
 238                         time stamp. If the cookie has no expiration time set, will return
 239                         <constant>NULL</constant>.
 240                     </para>
 241                 </listitem>
 242             </itemizedlist>
 243         </para>
 244
 245         <para>
 246             Additionally, several boolean tester methods are provided:
 247
 248             <itemizedlist>
 249                 <listitem>
 250                     <para>
 251                         <code>boolean isSecure()</code>: Check whether the cookie is set to be sent
 252                         over secure connections only. Generally speaking, if
 253                         <constant>TRUE</constant> the cookie should only be sent over
 254                         <acronym>HTTPS</acronym>.
 255                     </para>
 256                 </listitem>
 257
 258                 <listitem>
 259                     <para>
 260                         <code>boolean isExpired(int $time = null)</code>: Check whether the cookie
 261                         is expired or not. If the cookie has no expiration time, will always return
 262                         <constant>TRUE</constant>. If $time is provided, it will override the
 263                         current time stamp as the time to check the cookie against.
 264                     </para>
 265                 </listitem>
 266
 267                 <listitem>
 268                     <para>
 269                         <code>boolean isSessionCookie()</code>: Check whether the cookie is a
 270                         "session cookie" - that is a cookie with no expiration time, which is meant
 271                         to expire when the session ends.
 272                     </para>
 273                 </listitem>
 274             </itemizedlist>
 275         </para>
 276
 277         <para>
 278             <example id="zend.http.cookies.cookie.accessors.example-1">
 279                 <title>Using getter methods with Zend_Http_Cookie</title>
 280
 281                 <programlisting language="php"><![CDATA[
 282 // First, create the cookie
 283 $cookie =
 284     Zend_Http_Cookie::fromString('foo=two+words; ' +
 285                                  'domain=.example.com; ' +
 286                                  'path=/somedir; ' +
 287                                  'secure; ' +
 288                                  'expires=Wednesday, 28-Feb-05 20:41:22 UTC');
 289
 290 echo $cookie->getName();   // Will echo 'foo'
 291 echo $cookie->getValue();  // will echo 'two words'
 292 echo $cookie->getDomain(); // Will echo '.example.com'
 293 echo $cookie->getPath();   // Will echo '/'
 294
 295 echo date('Y-m-d', $cookie->getExpiryTime());
 296 // Will echo '2005-02-28'
 297
 298 echo ($cookie->isExpired() ? 'Yes' : 'No');
 299 // Will echo 'Yes'
 300
 301 echo ($cookie->isExpired(strtotime('2005-01-01') ? 'Yes' : 'No');
 302 // Will echo 'No'
 303
 304 echo ($cookie->isSessionCookie() ? 'Yes' : 'No');
 305 // Will echo 'No'
 306 ]]></programlisting>
 307             </example>
 308         </para>
 309     </sect2>
 310
 311     <sect2 id="zend.http.cookies.cookie.matching">
 312         <title>Zend_Http_Cookie: Matching against a scenario</title>
 313
 314         <para>
 315             The only real logic contained in a <classname>Zend_Http_Cookie</classname> object, is in
 316             the match() method. This method is used to test a cookie against a given
 317             <acronym>HTTP</acronym> request scenario, in order to tell whether the cookie should be
 318             sent in this request or not. The method has the following syntax and parameters:
 319             <code>boolean Zend_Http_Cookie->match(mixed $uri, [boolean $matchSessionCookies, [int
 320                 $now]]);</code>
 321
 322             <itemizedlist>
 323                 <listitem>
 324                     <para>
 325                         <code>mixed $uri</code>: A <classname>Zend_Uri_Http</classname> object with
 326                         a domain name and path to be checked. Optionally, a string representing a
 327                         valid <acronym>HTTP</acronym> <acronym>URL</acronym> can be passed instead.
 328                         The cookie will match if the <acronym>URL</acronym>'s scheme (HTTP or
 329                         <acronym>HTTPS</acronym>), domain and path all match.
 330                     </para>
 331                 </listitem>
 332
 333                 <listitem>
 334                     <para>
 335                         <code>boolean $matchSessionCookies</code>: Whether session cookies should be
 336                         matched or not. Defaults to <constant>TRUE</constant>. If set to
 337                         <constant>FALSE</constant>, cookies with no expiration time will never
 338                         match.
 339                     </para>
 340                 </listitem>
 341
 342                 <listitem>
 343                     <para>
 344                         <code>int $now</code>: Time (represented as UNIX time stamp) to check a
 345                         cookie against for expiration. If not specified, will default to the current
 346                         time.
 347                     </para>
 348                 </listitem>
 349             </itemizedlist>
 350
 351             <example id="zend.http.cookies.cookie.matching.example-1">
 352                 <title>Matching cookies</title>
 353
 354                 <programlisting language="php"><![CDATA[
 355 // Create the cookie object - first, a secure session cookie
 356 $cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
 357                                        'domain=.example.com; ' +
 358                                        'path=/somedir; ' +
 359                                        'secure;');
 360
 361 $cookie->match('https://www.example.com/somedir/foo.php');
 362 // Will return true
 363
 364 $cookie->match('http://www.example.com/somedir/foo.php');
 365 // Will return false, because the connection is not secure
 366
 367 $cookie->match('https://otherexample.com/somedir/foo.php');
 368 // Will return false, because the domain is wrong
 369
 370 $cookie->match('https://example.com/foo.php');
 371 // Will return false, because the path is wrong
 372
 373 $cookie->match('https://www.example.com/somedir/foo.php', false);
 374 // Will return false, because session cookies are not matched
 375
 376 $cookie->match('https://sub.domain.example.com/somedir/otherdir/foo.php');
 377 // Will return true
 378
 379 // Create another cookie object - now, not secure, with expiration time
 380 // in two hours
 381 $cookie = Zend_Http_Cookie::fromString('foo=two+words; ' +
 382                                        'domain=www.example.com; ' +
 383                                        'expires='
 384                                        . date(DATE_COOKIE, time() + 7200));
 385
 386 $cookie->match('http://www.example.com/');
 387 // Will return true
 388
 389 $cookie->match('https://www.example.com/');
 390 // Will return true - non secure cookies can go over secure connections
 391 // as well!
 392
 393 $cookie->match('http://subdomain.example.com/');
 394 // Will return false, because the domain is wrong
 395
 396 $cookie->match('http://www.example.com/', true, time() + (3 * 3600));
 397 // Will return false, because we added a time offset of +3 hours to
 398 // current time
 399 ]]></programlisting>
 400             </example>
 401         </para>
 402     </sect2>
 403
 404     <sect2 id="zend.http.cookies.cookiejar">
 405         <title>The Zend_Http_CookieJar Class: Instantiation</title>
 406
 407         <para>
 408             In most cases, there is no need to directly instantiate a
 409             <classname>Zend_Http_CookieJar</classname> object. If you want to attach a new cookie
 410             jar to your <classname>Zend_Http_Client</classname> object, just call the
 411             Zend_Http_Client->setCookieJar() method, and a new, empty cookie jar
 412             will be attached to your client. You could later get this cookie jar
 413             using Zend_Http_Client->getCookieJar().
 414         </para>
 415
 416         <para>
 417             If you still wish to manually instantiate a CookieJar object, you
 418             can do so by calling "new Zend_Http_CookieJar()" directly - the
 419             constructor method does not take any parameters. Another way to
 420             instantiate a CookieJar object is to use the static Zend_Http_CookieJar::fromResponse()
 421             method. This method takes two parameters: a <classname>Zend_Http_Response</classname>
 422             object, and a reference <acronym>URI</acronym>, as either a string or a
 423             <classname>Zend_Uri_Http</classname> object. This method will return a new
 424             <classname>Zend_Http_CookieJar</classname> object, already containing the cookies set by
 425             the passed <acronym>HTTP</acronym> response. The reference <acronym>URI</acronym> will
 426             be used to set the cookie's domain and path, if they are not defined in the Set-Cookie
 427             headers.
 428         </para>
 429     </sect2>
 430
 431     <sect2 id="zend.http.cookies.cookiejar.adding_cookies">
 432         <title>Adding Cookies to a Zend_Http_CookieJar object</title>
 433
 434         <para>
 435             Usually, the <classname>Zend_Http_Client</classname> object you attached your CookieJar
 436             object to will automatically add cookies set by <acronym>HTTP</acronym> responses to
 437             your jar. if you wish to manually add cookies to your jar, this can be done by using
 438             two methods:
 439
 440             <itemizedlist>
 441                 <listitem>
 442                     <para>
 443                         <classname>Zend_Http_CookieJar->addCookie($cookie[, $ref_uri])</classname>:
 444                         Add a single cookie to the jar. $cookie can be either a
 445                         <classname>Zend_Http_Cookie</classname> object or a string, which will be
 446                         converted automatically into a Cookie object. If a string is provided, you
 447                         should also provide $ref_uri - which is a reference <acronym>URI</acronym>
 448                         either as a string or <classname>Zend_Uri_Http</classname> object, to use as
 449                         the cookie's default domain and path.
 450                     </para>
 451                 </listitem>
 452
 453                 <listitem>
 454                     <para>
 455                         <classname>Zend_Http_CookieJar->addCookiesFromResponse($response,
 456                             $ref_uri)</classname>: Add all cookies set in a single
 457                         <acronym>HTTP</acronym> response to the jar. $response is expected to be a
 458                         <classname>Zend_Http_Response</classname> object with Set-Cookie headers.
 459                         $ref_uri is the request <acronym>URI</acronym>, either as a string or a
 460                         <classname>Zend_Uri_Http</classname> object, according to which the cookies'
 461                         default domain and path will be set.
 462                     </para>
 463                 </listitem>
 464             </itemizedlist>
 465         </para>
 466     </sect2>
 467
 468     <sect2 id="zend.http.cookies.cookiejar.getting_cookies">
 469         <title>Retrieving Cookies From a Zend_Http_CookieJar object</title>
 470
 471         <para>
 472             Just like with adding cookies, there is usually no need to manually
 473             fetch cookies from a CookieJar object. Your <classname>Zend_Http_Client</classname>
 474             object will automatically fetch the cookies required for an <acronym>HTTP</acronym>
 475             request for you. However, you can still use 3 provided methods to fetch
 476             cookies from the jar object: <methodname>getCookie()</methodname>,
 477             <methodname>getAllCookies()</methodname>, and
 478             <methodname>getMatchingCookies()</methodname>. Additionnaly, iterating over the
 479             CookieJar will let you retrieve all the <classname>Zend_Http_Cookie</classname> objects
 480             from it.
 481         </para>
 482
 483         <para>
 484             It is important to note that each one of these methods takes a
 485             special parameter, which sets the return type of the method. This
 486             parameter can have 3 values:
 487
 488             <itemizedlist>
 489                 <listitem>
 490                     <para>
 491                         <constant>Zend_Http_CookieJar::COOKIE_OBJECT</constant>: Return
 492                         a <classname>Zend_Http_Cookie</classname> object. If the method returns more
 493                         than one cookie, an array of objects will be returned.
 494                     </para>
 495                 </listitem>
 496
 497                 <listitem>
 498                     <para>
 499                         <constant>Zend_Http_CookieJar::COOKIE_STRING_ARRAY</constant>: Return
 500                         cookies as strings, in a "foo=bar" format, suitable for sending
 501                         in a <acronym>HTTP</acronym> request "Cookie" header. If more than one
 502                         cookie is returned, an array of strings is returned.
 503                     </para>
 504                 </listitem>
 505
 506                 <listitem>
 507                     <para>
 508                         <constant>Zend_Http_CookieJar::COOKIE_STRING_CONCAT</constant>: Similar to
 509                         COOKIE_STRING_ARRAY, but if more than one cookie is returned, this
 510                         method will concatenate all cookies into a single, long string
 511                         separated by semicolons (;), and return it. This is especially useful
 512                         if you want to directly send all matching cookies in a single
 513                         <acronym>HTTP</acronym> request "Cookie" header.
 514                     </para>
 515                 </listitem>
 516             </itemizedlist>
 517         </para>
 518
 519         <para>
 520             The structure of the different cookie-fetching methods is described below:
 521
 522             <itemizedlist>
 523                 <listitem>
 524                     <para>
 525                         <classname>Zend_Http_CookieJar->getCookie($uri, $cookie_name[,
 526                             $ret_as])</classname>: Get a single cookie from the jar, according to
 527                         its <acronym>URI</acronym> (domain and path) and name. $uri is either a
 528                         string or a <classname>Zend_Uri_Http</classname> object representing the
 529                         <acronym>URI</acronym>. $cookie_name is a string identifying the cookie
 530                         name. $ret_as specifies the return type as described above. $ret_type is
 531                         optional, and defaults to COOKIE_OBJECT.
 532                     </para>
 533                 </listitem>
 534
 535                 <listitem>
 536                     <para>
 537                         <classname>Zend_Http_CookieJar->getAllCookies($ret_as)</classname>: Get all
 538                         cookies from the jar. $ret_as specifies the return type as described
 539                         above. If not specified, $ret_type defaults to COOKIE_OBJECT.
 540                     </para>
 541                 </listitem>
 542
 543                 <listitem>
 544                     <para>
 545                         <classname>Zend_Http_CookieJar->getMatchingCookies($uri[,
 546                             $matchSessionCookies[, $ret_as[, $now]]])</classname>: Get all cookies
 547                         from the jar that match a specified scenario, that is a
 548                         <acronym>URI</acronym> and expiration time.
 549
 550                         <itemizedlist>
 551                             <listitem>
 552                                 <para>
 553                                     <varname>$uri</varname> is either a
 554                                     <classname>Zend_Uri_Http</classname> object or a string
 555                                     specifying the connection type (secure or non-secure), domain
 556                                     and path to match against.
 557                                 </para>
 558                             </listitem>
 559
 560                             <listitem>
 561                                 <para>
 562                                     <varname>$matchSessionCookies</varname> is a boolean telling
 563                                     whether to match session cookies or not. Session cookies are
 564                                     cookies that have no specified expiration time. Defaults to
 565                                     <constant>TRUE</constant>.
 566                                 </para>
 567                             </listitem>
 568
 569                             <listitem>
 570                                 <para>
 571                                     <varname>$ret_as</varname> specifies the return type as
 572                                     described above. If not specified, defaults to COOKIE_OBJECT.
 573                                 </para>
 574                             </listitem>
 575
 576                             <listitem>
 577                                 <para>
 578                                     <varname>$now</varname> is an integer representing the UNIX time
 579                                     stamp to consider as "now" - that is any cookies who are set to
 580                                     expire before this time will not be matched. If not specified,
 581                                     defaults to the current time.
 582                                 </para>
 583                             </listitem>
 584                         </itemizedlist>
 585
 586                         You can read more about cookie matching here:
 587                         <xref linkend="zend.http.cookies.cookie.matching" />.
 588                     </para>
 589                 </listitem>
 590             </itemizedlist>
 591         </para>
 592     </sect2>
 593 </sect1>
 594 <!--
 595 vim:se ts=4 sw=4 et:
 596 -->