Class Cookie_Jar

Cookie_Jar
Located in: Program_Root/Cookie_Jar.php
Cookie Jar class
This class should be used to handle cookies (storing cookies from HTTP response messages, and
sending out cookies in HTTP request messages).

This class is mainly based on Cookies.pm <http://search.cpan.org/author/GAAS/libwww-perl-5.65/
lib/HTTP/Cookies.pm> from the libwww-perl collection <http://www.linpro.no/lwp/>.
Unlike Cookies.pm, this class only supports the Netscape cookie spec
<http://wp.netscape.com/newsref/std/cookie_spec.html>, not RFC 2965.

I've been looking at both the Netscape cookie spec and RFC 2965, a lot of the functions will
be based on RFC 2965 simply because it covers details missed out by the netscape cookie spec.

Please consider this class in 'alpha' state at the moment, I've still got a lot of testing
to do, and will need to compare cookie handling with some existing browsers.
Any feedback appreciated.

Example:
  $options = array(
    'file_persistent' => 'cookies.txt',
    'autosave'        => true
   );
  $jar =& new Cookie_Jar($options);
  $jar->add_cookie_header($my_request);
  $jar->destroy();

See test_Cookie_Jar.php file for usage examples

Method Summary

 void constructor Cookie_Jar ( [$options = null] )
          Constructor - will accept an associative array holding the cookie jar options
 void add_cookie_header ( $request )
          Add cookie header - adds the relevant cookie header to the request message
 void clear ( [$domain = null], [$path = null], [$name = null] )
          Clear cookies - [domain [,path [,name]]] - call method with no arguments to clear all cookies.
 void clear_session_cookies ( )
          Clear session cookies - clears cookies which have no expiry time set
 void destroy ( )
          Destroy - an opplication using a cookie jar must call this method when it has
 void extract_cookies ( $response )
          Extract cookies - extracts cookies from the HTTP response message.
 string get_matching_cookies ( $param )
          Get matching cookies
 string get_option ( $option )
          Get option value
 bool load ( [$file = null] )
          Load - loads cookies from a netscape style cookies file.
 void parse_set_cookies ( $set_cookies, $param )
          Parse Set-Cookie values.
 bool save ( )
          Save cookies using files specified in the options.
 bool save_persistent_cookies ( [$file = null] )
          Save persistent cookies
 bool save_session_cookies ( [$file = null] )
          Save session cookies
 void scan ( $callback, &$param )
          Scan - goes through all cookies passing the values through the callback function.
 void set_cookie ( $domain, $path, $name, $value, [$secure = false], [$expires = null] )
          Set Cookie
 void set_option ( $option, [$value = null] )
          Set option - set cookie jar options.

Inherited Method Summary


Method Detail

constructor Cookie_Jar

void  constructor Cookie_Jar ( [$options = null] )

Constructor - will accept an associative array holding the cookie jar options

Function Parameters:
- array $options:
Function Info:

add_cookie_header

void  add_cookie_header ( $request )

Add cookie header - adds the relevant cookie header to the request message

Function Parameters:
- object $request: request object
Function Info:

clear

void  clear ( [$domain = null], [$path = null], [$name = null] )

Clear cookies - [domain [,path [,name]]] - call method with no arguments to clear all cookies.

Function Parameters:
- string $domain:
- string $path:
- string $name:
Function Info:

clear_session_cookies

void  clear_session_cookies ( )

Clear session cookies - clears cookies which have no expiry time set

Function Parameters:
Function Info:

destroy

void  destroy ( )

Destroy - an opplication using a cookie jar must call this method when it has
finished with the cookies.
Function Parameters:
Function Info:

extract_cookies

void  extract_cookies ( $response )

Extract cookies - extracts cookies from the HTTP response message.

Function Parameters:
- object $response:
Function Info:

get_matching_cookies

string  get_matching_cookies ( $param )

Get matching cookies
Only use this method if you cannot use add_cookie_header(), for example, if you want to use
this cookie jar class without using the request class.
Function Parameters:
- array $param: associative array containing 'domain', 'path', 'secure' keys
Function Info:
See - Cookie_Jar::add_cookie_header()

get_option

string  get_option ( $option )

Get option value

Function Parameters:
- string $option: option name
Function Info:
Return - false if option not found

load

bool  load ( [$file = null] )

Load - loads cookies from a netscape style cookies file.

Function Parameters:
- string $file: location of the file, or leave blank to use options
Function Info:

parse_set_cookies

void  parse_set_cookies ( $set_cookies, $param )

Parse Set-Cookie values.
Only use this method if you cannot use extract_cookies(), for example, if you want to use
this cookie jar class without using the response class.
Function Parameters:
- array $set_cookies: array holding 1 or more "Set-Cookie" header values
- array $param: associative array containing 'host', 'path' keys
Function Info:
See - Cookie_Jar::extract_cookies()

save

bool  save ( )

Save cookies using files specified in the options.

Function Parameters:
Function Info:

save_persistent_cookies

bool  save_persistent_cookies ( [$file = null] )

Save persistent cookies

Function Parameters:
- string $file: file to save to, leave out to use the "file_persistent" option value
Function Info:

save_session_cookies

bool  save_session_cookies ( [$file = null] )

Save session cookies

Function Parameters:
- string $file: file to save to, leave out to use the "file_session" option value
Function Info:

scan

void  scan ( $callback, &$param )

Scan - goes through all cookies passing the values through the callback function.
The callback function can be a method from another object (eg. array(&$my_obj, 'my_method')).
The callback function should accept 3 arguments:
 1- A reference to the cookie jar object (&$jar)
 2- An array holding all cookie parts, array is associative with the following keys: 
    ('domain','path','name','value','expires','secure')
 3- An optional parameter which can be used for whatever your function wants :),
    even though you might not have a use for this parameter, you need to define
    your function to accept it.  (Note: you can have this parameter be passed by reference)
The callback function should return a boolean, a value of 'true' will tell scan() you want
it to continue with the rest of the cookies, 'false' will tell scan() to not send any more
cookies to your callback function.

Example:
  // $jar is our cookie jar with some cookies loaded
  $name_to_delete = 'bla';
  $jar->scan('delete_name', $name_to_delete);

  // our callback function defined here
  function delete_name(&$jar, $cookie_parts, $name_to_delete) {
      if ($cookie_parts['name'] == $name_to_delete) {
          $jar->clear($cookie_parts['domain'], $cookie_parts['path'], $cookie_parts['name']);
      }
      // must return true to tell scan() to continue with cookies
      return true;
  }
Function Parameters:
- mixed $function: function name, or array holding an object and the method to call.
- mixed $param: passed as the 3rd argument to $function
Function Info:

set_cookie

void  set_cookie ( $domain, $path, $name, $value, [$secure = false], [$expires = null] )

Set Cookie

Function Parameters:
- string $domain:
- string $path:
- string $name: cookie name
- string $value: cookie value
- bool $secure:
- int $expires: expiry time (null if session cookie, <= 0 will delete cookie)
Function Info:

set_option

void  set_option ( $option, [$value = null] )

Set option - set cookie jar options.
RECOGNISED OPTIONS:
 - option name              values(s)          description
 ------------------------------------------------------------------------------
 - file_persistent          string             persistent cookie file location
 - file_session             string             session cookie file location
 - autosave                 bool               save cookies when destroy() is called
Function Parameters:
- mixed $option: option name to set, or associative array to replace all existing options
- string $value: option value, null to delete option
Function Info: