home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / Cookie.pod < prev    next >
Encoding:
Text File  |  2003-11-16  |  3.8 KB  |  157 lines
  1. =head1 NAME
  2.  
  3. Apache::Cookie - HTTP Cookies Class
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.     use Apache::Cookie ();
  8.     my $r = Apache->request;
  9.     my $cookie = Apache::Cookie->new($r, ...);
  10.  
  11. =head1 DESCRIPTION
  12.  
  13. The Apache::Cookie module is a Perl interface to the cookie routines
  14. in I<libapreq>.  The interface is based on Lincoln Stein's CGI::Cookie
  15. module.
  16.  
  17. =head1 Apache::Cookie METHODS
  18.  
  19. I<Apache::Cookie> does not export any symbols to the caller's namespace.
  20. Except for the request object passed to C<Apache::Cookie::new>, the OO
  21. interface is identical to I<CGI::Cookie>.  Please consult the L<CGI::Cookie>
  22. documentation for more details.
  23.  
  24. =head2 new
  25.  
  26. Just like CGI::Cookie::new, but requires an I<Apache> request object:
  27.  
  28.         my $cookie = Apache::Cookie->new($r,
  29.                              -name    =>  'foo', 
  30.                              -value   =>  'bar', 
  31.                              -expires =>  '+3M', 
  32.                              -domain  =>  '.capricorn.com', 
  33.                              -path    =>  '/cgi-bin/database',
  34.                              -secure  =>  1 
  35.                             ); 
  36.  
  37. The C<-value> attribute may be either an arrayref, a hashref, or
  38. an object with a C<freeze> method.  The <freeze> method must serialize
  39. the object in a manner compatible with the "value" portion of the 
  40. Cookie specs. Specifically, it must take care to avoid header tokens [;,=] 
  41. and whitespace characters in its output.
  42.  
  43. =head2 bake
  44.  
  45. Add a I<Set-Cookie> header to the outgoing headers table.
  46.  
  47.     $cookie->bake;
  48.  
  49. =head2 bake2
  50.  
  51. Add a I<Set-Cookie2> header to the outgoing headers table.
  52.  
  53.     $cookie->bake2;
  54.  
  55. =head2 fetch
  56.  
  57. Fetch and parse the incoming I<Cookie> header:
  58.  
  59.     my $cookies = Apache::Cookie->fetch($r); #hash ref
  60.  
  61.     my %cookies = Apache::Cookie->fetch($r);
  62.  
  63. =head2 as_string
  64.  
  65. Format the cookie object as a string:
  66.  
  67.  #same as $cookie->bake
  68.  $r->headers_out->add("Set-Cookie" => $cookie->as_string);
  69.  
  70. =head2 name
  71.  
  72. Get the name of the cookie:
  73.  
  74.  my $name = $cookie->name;
  75.  
  76. =head2 value
  77.  
  78. Get the value of the cookie:
  79.  
  80.  my $value = $cookie->value;
  81.  my @values = $cookie->value;
  82.  
  83. Note: if the cookie's value was serialized from an object possessing a 
  84. C<freeze> method, one way to reconstitute the object is by subclassing 
  85. Apache::Cookie with a package that provides the associated C<thaw> sub:
  86.  
  87.   package My::Cookie;
  88.   use base 'Apache::Cookie';
  89.   sub thaw { ... }
  90.   bless $cookie, __PACKAGE__;
  91.  
  92.   my $obj = $cookie->value;  # same as $cookie->thaw($cookie->raw_value);
  93.  
  94. =head2 raw_value
  95.  
  96. Gets the raw (opaque) value string as it appears in the incoming
  97. "Cookie" header.
  98.  
  99. =head2 domain
  100.  
  101. Get or set the domain for the cookie:
  102.  
  103.  my $domain = $cookie->domain;
  104.  $cookie->domain(".cp.net");
  105.  
  106. =head2 path
  107.  
  108. Get or set the path for the cookie:
  109.  
  110.  my $path = $cookie->path;
  111.  $cookie->path("/");
  112.  
  113. =head2 expires
  114.  
  115. Get or set the expire time for the cookie:
  116.  
  117.  my $expires = $cookie->expires;
  118.  $cookie->expires("+3h");
  119.  
  120. =head2 secure
  121.  
  122. Get or set the secure flag for the cookie:
  123.  
  124.  my $secure = $cookie->secure;
  125.  $cookie->secure(1);
  126.  
  127. =head1 CHANGES to the v1 API:
  128.  
  129. =over 4
  130.  
  131. =item * C<Apache::Cookie::fetch> requires an C<$r> object as (second) argument.
  132.  
  133. =item * C<Apache::Cookie::parse> is gone.
  134.  
  135. =item * C<Apache::Cookie::new> can take an object as its -value arg, assuming
  136.         the object has a valid C<freeze> method.
  137.  
  138. =item * C<name> and <value> no longer accept a "set" argument. In other words,
  139.         neither a cookie's name, nor its value, may be modified.  A new cookie
  140.         should be made instead.
  141.  
  142. =back
  143.  
  144. =head1 BUGS
  145.  
  146. =head1 SEE ALSO
  147.  
  148. Apache(3), Apache::Request(3), CGI::Cookie(3)
  149.  
  150. =head1 AUTHORS
  151.  
  152. Doug MacEachern, Joe Schaefer, Issac Goldstand
  153.  
  154. =head1 MISSING DOCS
  155.  
  156. Apache::Cookie::Jar, Apache::Cookie::Table
  157.