03-session.sgml

PHPLOB注释详细版 使用模板技术的好帮手 PHP最有用的东东了

<!-- $Id: 03-session.sgml,v 1.2 2000/04/17 16:48:32 kk Exp $ -->

<sect1>Session
<p>

The session class keeps a list of global variable names and
provides a set of functions to load and save these variables
from and to a data storage container (we will call it container
for shortness). The named variables may be scalar
variables (strings, integers and floats) or arrays. Objects are
handled as well, provided they implement two instance variables
naming their class and enumerating their (persistent) slots.

<sect2>Instance variables
<p>

<table>
<tabular ca="">
classname<colsep>Serialization helper: The name of this class.<rowsep>
magic<colsep>A secret string used in ID creation. Change it!<rowsep>
mode     <colsep>Mode of Session ID propagation. Either <tt/cookie/ or <tt/get/.<rowsep>
fallback&lowbar;mode<colsep>Mode of Session ID propagation should <tt/$mode/ not work. Set <tt/$mode/ to <tt/cookie/ and <tt/$fallback&lowbar;mode/ to <tt/get/.<rowsep>
lifetime <colsep>Lifetime of the session cookie in minutes or 0 to use session cookies.<rowsep>
gc&lowbar;time<colsep>Garbage collection tuning parameter, see below.<rowsep>
gc&lowbar;probability<colsep>Garbage collection tuning parameter, see below.<rowsep>
allowcache<colsep>Control caching of session pages. If set to <tt/passive/ (also the default), no cache-control headers are being sent. If set to <tt/no/, the page is not cached under HTTP/1.1 or HTTP/1.0; if set to <tt/public/ , the page is publically cached under HTTP/1.1 and HTTP/1.0; if set to <tt/private/ , the page is privately cached under HTTP/1.1 and not cached under HTTP/1.0<rowsep>
allowcache&lowbar;expire<colsep>When caching is allowed, the pages can be cached for this many minutes.<rowsep>
that&lowbar;class<colsep>A classname. Session uses this class to store and retrieve data.<rowsep>
auto&lowbar;init<colsep>The file to be loaded on session establishment.<rowsep>
secure&lowbar;auto&lowbar;init<colsep>Set to 0, if all pages always call
page&lowbar;close() (This is never the case!).<rowsep>
</tabular>
<caption>Accessible instance variables.</caption>
</table>

<table>
<tabular ca="">
pt<colsep>Internal array of names of persistent variables.<rowsep>
in<colsep>Flag: If set, auto&lowbar;init has been executed.<rowsep>
name<colsep>A tag (name) for the session type.<rowsep>
id<colsep>Id of the current session.<rowsep>
that<colsep>Container object instance.<rowsep>
</tabular>
<caption>Internal instance variables.</caption>
</table>

<sect2>Instance methods
<p>

<sect3>Accessible instance methods
<p>

<descrip>
<tag>register($varname)</tag>
<p>Registers a global variable name as a session variable. The
   name may identify a scalar variable, an array or an object.
   If an object is to be made persistent, it must have two
   instance variables:
  
   <descrip>
   <tag>classname</tag>
   <p>A string with the name of the objects class.
   <tag> persistent&lowbar;slots</tag>
   <p>An array with the names of all object slots to save.
   </descrip>

<tag>unregister($varname)</tag>
<p>Unregisters a global variable name as a session variable.
   The variable is not deleted, but its value will be lost
   at the end of a page. It is no longer saved to the database.

<tag>is_registered($varname)</tag>
<p>Returns true if the variable named $varname is registered
   with the session, false otherwise.

<tag>delete()</tag>
<p>Destroy the current session and put&lowbar;id() the current session
   id.

   After <tt/delete()/ has been executed, all session data has
   been removed from the database. Also, the session object is
   unusable on this page. Consequently, <tt/page&lowbar;close()/ may
   not be called for this session. Session variables are still
   available on this page, even after the <tt/delete()/, but
   will be lost on the following pages.

   In cookie mode, it is possible to <tt/page&lowbar;open()/ a new
   session after <tt/delete()/ has been called, if no HTML has
   been output so far so that the new cookie can be set. If you
   do this, you can also re-register some of the previous
   session variables and can call <tt/page&lowbar;close()/ for the new
   session.  This allows you to change the session on the fly
   and selectively carry over session data from the previous
   session.
   
<tag>url($url)</tag>
<p>
Return an URL referencing the current session. If in <tt/get/
mode, the current session id is attached to this URL, else the
URL is returned unmodified.

<tag>purl($url)</tag>
<p>
A shorthand for <tt/print $this-&gt;url($url);/

<tag>self&lowbar;url()</tag>
<p>
Return an URL referencing the current page, including
<tt/PHP&lowbar;SELF/ and <tt/QUERY&lowbar;STRING/ information.
If in <tt/get/ mode, the session id is included.

<tag>pself&lowbar;url()</tag>
<p>
A shorthand for <tt/print $this-&gt;self&lowbar;url()/.

<tag>hidden&lowbar;session()</tag>
<p>
Adds a hidden form element containing the session name and id.

<tag>add&lowbar;query($qarray)</tag>
<p>

Return string to be appended to the current URL for parameters
in GET query format. Intended usage is like this:

<tscreen><code>

&lt;a href="<&lt;?
$sess->pself_url().$sess-&gt;padd_query(array("again"=&gt;"yes"))
?&gt;"&gt; Reload&lt;/a&gt; and log in?

</code></tscreen>

<tag>padd&lowbar;query($qarray)</tag>
<p>

A shorthand for <tt/print $this-&gt; add&lowbar;query($qarray)/.

<tag>reimport&lowbar;get&lowbar;vars()</tag>
<p>

When a <tt/FORM/ variable is made persistent, that form variable is
imported into PHP, then page&lowbar;open() is being called and
the new variable value is overwritten from the database. The
<tt/FORM/ value is lost.
<p>

If you had enabled <tt/track&lowbar;vars/ and were accessing
<tt/HTTP&lowbar;GET&lowbar;VARS/ directly, which is recommended,
this were not a problem. Some legacy scripts rely on persistent
<tt/FORM/ input variables, though.
<p>

These scripts may call the appropriate
<tt/reimport/&lowbar;x&lowbar;<tt/vars()/ functions. These
functions will re-read the tracked variable arrays and
reinitialize the appropriate global variables after session
variables have been restored.
<p>

Use of this function is discouraged.

<tag>reimport&lowbar;post&lowbar;vars()</tag>
<p>
See <tt/reimport&lowbar;get&lowbar;vars()/.

<tag>reimport&lowbar;cookie&lowbar;vars()</tag>
<p>
See <tt/reimport&lowbar;get&lowbar;vars()/.

<tag>set&lowbar;container()</tag>
<p>
You shall not call this function directly. It is called back by the
<tt/start()/ function of <tt/Session()/ during initializiation.
It is documented so that you can override its implementation in
your subclass of <tt/Session/ if you know what you are doing.

This function creates and starts the container class used by
this instance of session.

<tag>set&lowbar;tokenname()</tag>
<p>
You shall not call this function directly. It is called back by the
<tt/start()/ function of <tt/Session()/ during initializiation.
It is documented so that you can override its implementation in
your subclass of <tt/Session/ if you know what you are doing.

This function determines and sets the internal session name.

<tag>release&lowbar;token()</tag>
<p>
You shall not call this function directly. It is called back by the
<tt/start()/ function of <tt/Session()/ during initializiation.
It is documented so that you can override its implementation in
your subclass of <tt/Session/ if you know what you are doing.

This function determines the current method of session
propagation and determines if a new session token has to be
generated.

<tag>put&lowbar;headers()</tag>
<p>
You shall not call this function directly. It is called back by the
<tt/start()/ function of <tt/Session()/ during initializiation.
It is documented so that you can override its implementation in
your subclass of <tt/Session/ if you know what you are doing.

This function determines which header lines are to be generated
by the session, including cache control headers.
</descrip>

<sect3>Internal instance methods
<p>

<descrip>
<tag>get&lowbar;id()</tag>
<p>
See <tt/get&lowbar;id()/.

<tag>get&lowbar;id($id&lowbar;to&lowbar;use)</tag>
<p>get&lowbar;id() is used internally to determine a session
   identifier.  Currently, a session identifier is a hex number
   of 32 characters (128 bits) and it is generated by
   md5(uniqid($this->magic)) to make it hard to guess.
  
   get&lowbar;id() may be called with an optional session id to use as
   a parameter. This is useful if you want to change a session
   id without breaking the session (taking over an old, left
   over session).
  
   get&lowbar;id() can be overwritten by a subclass, if you want a
   different system to create session ids. For example, some
   applications want to use a constant session id that is not
   propagated to the client to use a shared pool of persistent
   variables (a guestbook for example). These applications need
   locking (to be implemented soon).

<tag>put&lowbar;id()</tag>
<p>put&lowbar;id() is used internally to "unuse" a session it. At the
   moment it deletes the client side cookie and deletes
   $HTTP&lowbar;COOKIE&lowbar;VAR[$this->name] for that cookie. The variable
   ${$this->name} is <em/not/ deleted.

<tag>serialize($prefix, &$str)</tag>
<p>serialize() is used internally to append to str all PHP
   code needed to reconstruct the variable named in prefix.

<tag>freeze()</tag>
<p>freeze() serializes all register()ed variables and writes
   the resulting code into the database, tagged with the
   current session id and the current session name.

<tag>thaw()</tag>
<p>thaw() loads a set of freeze()ed variables for the current
   session id and session name out of the database and
   recreates them.

<tag>gc()</tag>
<p>The <tt/active&lowbar;sessions/ table contains one row for
   each session. That row is uniquely identified by the <tt/sid/
   and <tt/name/ values (<tt/name/ is the name of the session
   class that has written the row). Each time that row is written,
   the column <tt/changed/ is updated with the current time.
   
   The gc() function deletes all rows that are older than
   <tt/gc&lowbar;time/ minutes and have a matching <tt/name/ 
   field. For speed reasons, gc() is not not called every time
   an update to <tt/active&lowbar;sessions/ is being made.
   Instead it is called randomly with a probability of
   <tt/gc&lowbar;probability/.

<tag>reimport&lowbar;any&lowbar;vars($arrayname)</tag>
<p>Used to implement the three official reimport functions.

<tag>start()</tag>
<p>Initialization function, to be called after object
   instantiation. Calls get&lowbar;id() to get the current session id,
   creates a database connection, then calls thaw() to load all
   session variables. Randomly activates gc(). Checks <tt/allowcache/
   to send proper headers to control browser caching.

</descrip>
<p>