documentation-3.html

来自「PHPLOB注释详细版 使用模板技术的好帮手 PHP最有用的东东了」· HTML 代码 · 共 1,596 行 · 第 1/5 页

<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Ldap extends CT_Ldap {
        var $classname = "My_Ldap";
        var $ldap_host = "localhost";
        var $ldap_port = 389;
        var $basedn = "dc=your-domain, dc=com";
        var $rootdn = "cn=root, dc=your-domain, dc=com";
        var $rootpw = "secret";
        var $objclass = "phplibdata";
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>You can then use My_Ldap in class Session. Reference it
by putting "My_Ldap" in the "that_class" variable.
<P>
<P>
<H2><A NAME="ss3.8">3.8 Session</A>
</H2>

<P>
<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.
<P>
<H3>Instance variables</H3>

<P>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
classname</TD><TD>Serialization helper: The name of this class.</TD></TR><TR><TD>
magic</TD><TD>A secret string used in ID creation. Change it!</TD></TR><TR><TD>
mode </TD><TD>Mode of Session ID propagation. Either <CODE>cookie</CODE> or <CODE>get</CODE>.</TD></TR><TR><TD>
fallback_mode</TD><TD>Mode of Session ID propagation should <CODE>$mode</CODE> not work. Set <CODE>$mode</CODE> to <CODE>cookie</CODE> and <CODE>$fallback_mode</CODE> to <CODE>get</CODE>.</TD></TR><TR><TD>
lifetime </TD><TD>Lifetime of the session cookie in minutes or 0 to use session cookies.</TD></TR><TR><TD>
gc_time</TD><TD>Garbage collection tuning parameter, see below.</TD></TR><TR><TD>
gc_probability</TD><TD>Garbage collection tuning parameter, see below.</TD></TR><TR><TD>
allowcache</TD><TD>Control caching of session pages. If set to <CODE>passive</CODE> (also the default), no cache-control headers are being sent. If set to <CODE>no</CODE>, the page is not cached under HTTP/1.1 or HTTP/1.0; if set to <CODE>public</CODE> , the page is publically cached under HTTP/1.1 and HTTP/1.0; if set to <CODE>private</CODE> , the page is privately cached under HTTP/1.1 and not cached under HTTP/1.0</TD></TR><TR><TD>
allowcache_expire</TD><TD>When caching is allowed, the pages can be cached for this many minutes.</TD></TR><TR><TD>
that_class</TD><TD>A classname. Session uses this class to store and retrieve data.</TD></TR><TR><TD>
auto_init</TD><TD>The file to be loaded on session establishment.</TD></TR><TR><TD>
secure_auto_init</TD><TD>Set to 0, if all pages always callpage_close() (This is never the case!).</TD></TR><TR><TD>

<CAPTION>Accessible instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
pt</TD><TD>Internal array of names of persistent variables.</TD></TR><TR><TD>
in</TD><TD>Flag: If set, auto_init has been executed.</TD></TR><TR><TD>
name</TD><TD>A tag (name) for the session type.</TD></TR><TR><TD>
id</TD><TD>Id of the current session.</TD></TR><TR><TD>
that</TD><TD>Container object instance.</TD></TR><TR><TD>

<CAPTION>Internal instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<H3>Instance methods</H3>

<P>
<P>
<H3>Accessible instance methods</H3>

<P>
<P>
<DL>
<DT><B>register($varname)</B><DD><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:
<P>
<DL>
<DT><B>classname</B><DD><P>A string with the name of the objects class.
<DT><B> persistent_slots</B><DD><P>An array with the names of all object slots to save.
</DL>
<P>
<DT><B>unregister($varname)</B><DD><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.
<P>
<DT><B>is_registered($varname)</B><DD><P>Returns true if the variable named $varname is registered
with the session, false otherwise.
<P>
<DT><B>delete()</B><DD><P>Destroy the current session and put_id() the current session
id.
<P>After <CODE>delete()</CODE> has been executed, all session data has
been removed from the database. Also, the session object is
unusable on this page. Consequently, <CODE>page_close()</CODE> may
not be called for this session. Session variables are still
available on this page, even after the <CODE>delete()</CODE>, but
will be lost on the following pages.
<P>In cookie mode, it is possible to <CODE>page_open()</CODE> a new
session after <CODE>delete()</CODE> 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 <CODE>page_close()</CODE> for the new
session.  This allows you to change the session on the fly
and selectively carry over session data from the previous
session.
<P>
<DT><B>url($url)</B><DD><P>Return an URL referencing the current session. If in <CODE>get</CODE>
mode, the current session id is attached to this URL, else the
URL is returned unmodified.
<P>
<DT><B>purl($url)</B><DD><P>A shorthand for <CODE>print $this-&gt;url($url);</CODE>
<P>
<DT><B>self_url()</B><DD><P>Return an URL referencing the current page, including
<CODE>PHP_SELF</CODE> and <CODE>QUERY_STRING</CODE> information.
If in <CODE>get</CODE> mode, the session id is included.
<P>
<DT><B>pself_url()</B><DD><P>A shorthand for <CODE>print $this-&gt;self_url()</CODE>.
<P>
<DT><B>hidden_session()</B><DD><P>Adds a hidden form element containing the session name and id.
<P>
<DT><B>add_query($qarray)</B><DD><P>
<P>Return string to be appended to the current URL for parameters
in GET query format. Intended usage is like this:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>

&lt;a href="&lt;&lt;?
$sess->pself_url().$sess-&gt;padd_query(array("again"=&gt;"yes"))
?&gt;"&gt; Reload&lt;/a&gt; and log in?
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<DT><B>padd_query($qarray)</B><DD><P>
<P>A shorthand for <CODE>print $this-&gt; add_query($qarray)</CODE>.
<P>
<DT><B>reimport_get_vars()</B><DD><P>
<P>When a <CODE>FORM</CODE> variable is made persistent, that form variable is
imported into PHP, then page_open() is being called and
the new variable value is overwritten from the database. The
<CODE>FORM</CODE> value is lost.
<P>
<P>If you had enabled <CODE>track_vars</CODE> and were accessing
<CODE>HTTP_GET_VARS</CODE> directly, which is recommended,
this were not a problem. Some legacy scripts rely on persistent
<CODE>FORM</CODE> input variables, though.
<P>
<P>These scripts may call the appropriate
<CODE>reimport</CODE>_x_<CODE>vars()</CODE> functions. These
functions will re-read the tracked variable arrays and
reinitialize the appropriate global variables after session
variables have been restored.
<P>
<P>Use of this function is discouraged.
<P>
<DT><B>reimport_post_vars()</B><DD><P>See <CODE>reimport_get_vars()</CODE>.
<P>
<DT><B>reimport_cookie_vars()</B><DD><P>See <CODE>reimport_get_vars()</CODE>.
<P>
<DT><B>set_container()</B><DD><P>You shall not call this function directly. It is called back by the
<CODE>start()</CODE> function of <CODE>Session()</CODE> during initializiation.
It is documented so that you can override its implementation in
your subclass of <CODE>Session</CODE> if you know what you are doing.
<P>This function creates and starts the container class used by
this instance of session.
<P>
<DT><B>set_tokenname()</B><DD><P>You shall not call this function directly. It is called back by the
<CODE>start()</CODE> function of <CODE>Session()</CODE> during initializiation.
It is documented so that you can override its implementation in
your subclass of <CODE>Session</CODE> if you know what you are doing.
<P>This function determines and sets the internal session name.
<P>
<DT><B>release_token()</B><DD><P>You shall not call this function directly. It is called back by the
<CODE>start()</CODE> function of <CODE>Session()</CODE> during initializiation.
It is documented so that you can override its implementation in
your subclass of <CODE>Session</CODE> if you know what you are doing.
<P>This function determines the current method of session
propagation and determines if a new session token has to be
generated.
<P>
<DT><B>put_headers()</B><DD><P>You shall not call this function directly. It is called back by the
<CODE>start()</CODE> function of <CODE>Session()</CODE> during initializiation.
It is documented so that you can override its implementation in
your subclass of <CODE>Session</CODE> if you know what you are doing.
<P>This function determines which header lines are to be generated
by the session, including cache control headers.
</DL>
<P>
<H3>Internal instance methods</H3>

<P>
<P>
<DL>
<DT><B>get_id()</B><DD><P>See <CODE>get_id()</CODE>.
<P>
<DT><B>get_id($id_to_use)</B><DD><P>get_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.
<P>get_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).
<P>get_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).
<P>
<DT><B>put_id()</B><DD><P>put_id() is used internally to "unuse" a session it. At the
moment it deletes the client side cookie and deletes
$HTTP_COOKIE_VAR[$this->name] for that cookie. The variable
${$this->name} is <EM>not</EM> deleted.
<P>
<DT><B>serialize($prefix, &amp;$str)</B><DD><P>serialize() is used internally to append to str all PHP
code needed to reconstruct the variable named in prefix.
<P>
<DT><B>freeze()</B><DD><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.
<P>
<DT><B>thaw()</B><DD><P>thaw() loads a set of freeze()ed variables for the current
session id and session name out of the database and
recreates them.
<P>
<DT><B>gc()</B><DD><P>The <CODE>active_sessions</CODE> table contains one row for
each session. That row is uniquely identified by the <CODE>sid</CODE>
and <CODE>name</CODE> values (<CODE>name</CODE> is the name of the session
class that has written the row). Each time that row is written,
the column <CODE>changed</CODE> is updated with the current time.
<P>The gc() function deletes all rows that are older than
<CODE>gc_time</CODE> minutes and have a matching <CODE>name</CODE> 
field. For speed reasons, gc() is not not called every time
an update to <CODE>active_sessions</CODE> is being made.
Instead it is called randomly with a probability of
<CODE>gc_probability</CODE>.
<P>
<DT><B>reimport_any_vars($arrayname)</B><DD><P>Used to implement the three official reimport functions.
<P>
<DT><B>start()</B><DD><P>Initialization function, to be called after object
instantiation. Calls get_id() to get the current session id,
creates a database connection, then calls thaw() to load all
session variables. Randomly activates gc(). Checks <CODE>allowcache</CODE>
to send proper headers to control browser caching.
<P>
</DL>
<P>
<P>
<H3>Example</H3>

<P>Use a subclass to provide the appropriate parameters to your
session. Usually your subclass looks like this:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Session extends Session {
  var $classname = "My_Session"; ## Persistence support
  
  var $mode      = "cookie";
  var $lifetime  = 0;            ## use session cookies
  
  ## which container to use
  var $that_class = "Session_sql";
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Remember that you have to provide a <CODE>DB_Sql</CODE> subclass
with the parameters needed to access your database.
<P>Use the page management functions (see above) to use your
session subclass. The feature name for session management is
<CODE>sess</CODE>; provide the name of your session subclass as a
parameter to the sess feature:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
  page_open(array("sess" =&gt; "My_Session"));
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Use the <CODE>register()</CODE> instance method to register variables as
persistent. If <CODE>$sess</CODE> is your session object, use
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
$sess-&gt;register("s");
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>to make the global variable <CODE>$s</CODE> persistent. <CODE>$s</CODE> may be a
scalar value, an array or an object with persistence support
slots.
<P>Do not use the instance methods <CODE>freeze()</CODE> and <CODE>thaw()</CODE>
directly, but use the page management functions instead.
<P>To have some pages cached and others not cached, use multiple
instances of the session object. For example, for those pages
that should be cached, use a session object instance like
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Cached_Session extends My_Session {
  ## pages that use this session instance are cached.
  var $allowcache = "private";
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Be careful when using the <CODE>public</CODE> cache option. Publically cached pages
may be accessible to unauthenticated users. The <CODE>private</CODE> cache option
prevents unauthenticated access, but is only functional in HTTP/1.1 browsers.
<P>
<H3>Using "auto_init"</H3>