documentation-3.html

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

<P>
<P>You may define <CODE>$sess->auto_init</CODE> to the name of an include
file in your extension of session. Per convention, the name
<CODE>setup.inc</CODE> is being used.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Session extends Session {
  var $classname = "My_Session";
  var $magic     = "Calvin+Hobbes";
  var $mode      = "cookie";
  var $gc_probability = 5;

  var $auto_init = "setup.inc";   // name of auto_init file.
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Whenever a new session is established, that is, a user without a
session id connects to your application, the auto_init file is
included and executed exactly once. The file is executed from
within the context of the <CODE>page_open()</CODE> function, that is,
<EM>not</EM> within a global context. To define or access global
variables from the auto_init file, you have to <CODE>global</CODE> them.
<P>When auto_init is being executed, all features of your page
already exist and are available globally.
That is, you can safely rely on
the existence of the <CODE>$sess</CODE>, <CODE>$auth</CODE>, <CODE>$perm</CODE> and
<CODE>$user</CODE> variables, if your application specifies them.
<EM>Note</EM> that you cannot in general know which particular page
triggered the execution of auto_init, though. If you have some
pages that request authentication and others that don't, you
cannot rely on the presence of the <CODE>$auth</CODE> object in general,
but have to test for it with <CODE>is_object($auth)</CODE> before
accessing it.
<P>The auto_init file is the appropriate place to initialize and
register all your session variables. A sample <CODE>setup.inc</CODE> may
look like this:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
global $lang;   // application language
$lang = "de";   // german by default
$sess-&gt;register("lang");

global $cur;   // application currency
$cur = "EUR";   // Euro by default
$sess-&gt;register("cur");

global $cart;
$cart = new Shop_Cart;      // Create a shopping cart object as defined in local.inc
$sess-&gt;register("cart"); // register it.
?&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P><EM>Note:</EM> If you don't use a fallback_mode and you get users
that turn off cookies, these users will force a new session each
time they hit any page of your application. Of course this will
force inclusion and execution of <CODE>setup.inc</CODE> for each page
they visit, too. Nothing can be done about this.
<P>
<H3>Unregistering variables and deleting sessions</H3>

<P>To get rid of a persistent variable, call
<CODE>$sess-&gt;unregister()</CODE> with the name of that variable. The
value of the formerly registered variable is still available
after the call to unregister, but the variable is no longer
persistent and will be lost at the end of the current page.
<P>To get rid of all session related data including the session
record in the database, the current session id and the session
cookie in the users browser, call <CODE>$sess-&gt;delete()</CODE>. In
shopping applications this is commonly done when the user
commits his order to get rid of the current shopping cart and
everything else. You may want to remember selected information
about that user, though, as shown below.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
  page_open(array("sess" =&gt; "Shop_Session"));

  // send order as mail
  mail_order($shopowner, $user, $cart);

  // delete the current session
  $sess->delete();

  // now get a new session id, but retain the users
  // address and name:
  page_open(array("sess" =&gt; "Shop_Session")); // will force auto_init again!
  $sess->register("user");  // could be done in auto_init as well

?&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Reading and understanding session data for debugging</H3>

<P>When debugging PHPLIB applications, it is often useful to be
able to read and understand the contents of the active_sessions
table. Each session is represented by a single line in this
table. The primary key to this table is the pair <CODE>name</CODE> and
<CODE>sid</CODE>. <CODE>name</CODE> is the content of <CODE>$this-&gt;name</CODE> and
is usually the classname of your session class. <CODE>sid</CODE> is the
content of <CODE>$this-&gt;id</CODE> and is usually the MD5 hash of a
uniqid and some magic string.
<P>By choosing a pair, it is possible for PHPLIB to have more than
one session type (for example, session and user data, see the
<CODE>User</CODE> class below) per application and store all this data
in a single table. If you are debugging a session class, for
example <CODE>Example_Session</CODE>, only records where <CODE>name =
"Example_Session"</CODE> are of interest to you. Determine the current
session id of your <CODE>Example_Session</CODE> by printing <CODE>$sess->id</CODE>
and select the record with that <CODE>name</CODE> and <CODE>sid</CODE> from the
database.
<P>The <CODE>changed</CODE> field indicates when this record has been
updated the last time. It is a 14 character (Y2K compliant)
string of the format YYYYMMDDhhmmss. Ordering by <CODE>changed</CODE>
desc will show you the most current session records first (the
MySQL "limit" clause may come in handy here).
<P>The <CODE>val</CODE> column of a session record contains a PHP program
that can be safely fed to <CODE>stripslashes()</CODE> first and
<CODE>eval()</CODE> after that. The PHP program consists entirely of
assignments and contains all instructions necessary to recreate
the persistent variables. The structure and order of
instructions within this program is always the same.
<P>First item is always an assignment to <CODE>$this-&gt;in</CODE>. If set
to 1, auto_init has been executed by this session. If
<EM>not</EM> set to 1, auto_init has not been executed, yet.
This may be because no auto_init file is defined for
that session.
<P>After that comes code like this: <CODE>$this-&gt;pt = array();</CODE>
followed by a bunch of assignments like
<CODE>$this-&gt;pt["somestring"] = 1;</CODE>. Each somestring is the
name of a registered variable. Variable registrations are
persistent themselves and are saved with the <CODE>$this-&gt;pt</CODE>
array. Even if the variable in question is not set, it may be
registered and stays so until it is unregistered or the session
is deleted. Check the contents of the pt array is you want to
see which variables are currently registered with your session.
<P>Finally, the actual contents of your variables are saved. This
is always done by accessing the $GLOBALS array and always by
enumerating the scalar values that make up the persistent
variable. For a scalar, you will see code like
<CODE>$GLOBALS[somevar] = "value";</CODE>. 
<P>For an array, first <CODE>$GLOBALS[someary] = array();</CODE>
is generated. Then the scalars that make up the array, if any,
are written out, generating code that looks like
<CODE>$GLOBALS[someary][index] = "value"</CODE>.
<P>And for objects, code to create an object instance is saved:
<CODE>$GLOBALS[someobj] = new Classname;</CODE>. "Classname"
is taken from the objects <CODE>$classname</CODE> slot, which <EM>must</EM>
be present and accurate. Then the scalars that are to be saved
are written out, according to the contents of the objects
<CODE>persistent_slots</CODE> array:
<CODE>$GLOBALS[someobj]-&gt;slot = "value";</CODE> is written.
<P>If you want to see what values have been saved to the
database, you just have to look at the <CODE>$GLOBALS</CODE> assignments
for that session.
<P>
<H3>How "serialize()" operates</H3>

<P>
<P>The following information is applicable only to library
developers, that is, programmers that want to change the
internal workings of PHPLIB. You may safely skip this section;
some information here requires advanced understanding of the PHP
language.
<P>The heart of the session class is the <CODE>serialize()</CODE> internal
function. This function takes an expression called prefix and
generates PHP code that will assign the value of that expression
to the expression when executed. For example, if the expression
is <CODE>$GLOBALS["a"]</CODE> and the global variable <CODE>$a</CODE>
has the value <CODE>17</CODE>, then serialize will create the PHP
program <CODE>$GLOBALS["a"] = "17";</CODE>. To save memory,
<CODE>serialize()</CODE> operates on a reference parameter <CODE>$str</CODE>,
where is will append the code generated.
<P>First thing <CODE>serialize()</CODE> does is to determine the type of
the current expression using the PHP <CODE>gettype()</CODE> function.
The current type is stored in <CODE>$t</CODE>. The type of the
expression may indicate either a scalar value (integer number,
float number or string), an array or an object.
<P>Scalar values are the easiest to handle: <CODE>serialize()</CODE> just
evaluates the current expression and remembers the result value
in <CODE>$l</CODE>. An assignment is generated that will assign the
current value to the current expression. Since the current value
may be a string and that string may contain bad characters (any
of backslash, double quotes or dollar sign), these characters
are backslashed. We are done, <CODE>serialize()</CODE> ends here for
scalars.
<P>In the case of <CODE>$t</CODE> indicating an array, code is generated to
create an empty array (<CODE>expression = array();</CODE>). Then the
keys of current expression are enumerated and for each key
<CODE>serialize()</CODE> is called recursively with the current key
appended to the expression. That will append code for each array
slot.
<P>Should <CODE>$t</CODE> indicate an object, code is generated to create
that object (<CODE>expression = new Classname;</CODE>). Since one cannot
find out the name of the class of an object for arbitrary
objects in PHP, objects handled by <CODE>serialize()</CODE> must have a
slot named <CODE>classname</CODE>. The object handler will then
enumerate the contents of the objects slot <CODE>persistent_slots</CODE>
and call <CODE>serialize()</CODE> recursively for each of these slots
with the appropriate prefix.
<P>Since many of the expressions used in <CODE>serialize()</CODE> require
variable variable names or even variable code, <CODE>eval()</CODE> is
used liberally. Unfortunately, this makes the code hard to read.
<P>
<H2><A NAME="ss3.9">3.9 Auth</A>
</H2>

<P>
<P>Authentication management can be used to authenticate a session,
that is, to identify the user at the client side of the session.
<P>Authentication is done inline, with HTML forms, <EM>not</EM> with
HTTP authentication (that's the browser popup you get when you
hit a page protected with htaccess). Inline authentication has
several advantages over HTTP authentication:
<P>
<UL>
<LI>It can be undone: A session can be un-authenticated, the
user can "log out".</LI>
<LI>It can expire: A session can automatically be
un-authenticated after a given idle time.</LI>
<LI>It can be customized: You are not limited to user/password
pairs. Instead you could use a customer number, operator id
and a password to log in. Also, you have full control over
the login screen, which is a normal HTML page with logos,
help and forms as you see fit.</LI>
<LI>It is database based. Authentication is being done against
a database of your design, not a htpasswd text file.</LI>
<LI>It is per page. You decide on a per-page basis which pages
are authenticated and which aren't.</LI>
<LI>It can be user authenticating and optionally self
registering. In <EM>registration</EM> mode, a user without a valid login is
encouraged to register and an account is created for this
user.</LI>
<LI>It works with CGI PHP. HTTP authentication is available
only in mod_php.</LI>
<LI>It is integrated with a permission checking scheme.</LI>
</UL>
<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>
persistent_slots</TD><TD>Serialization helper: The names of all persistent slots.</TD></TR><TR><TD>
lifetime</TD><TD>Maximum allowed idle time before the authentication expires. If set to 0, The authentication never expires (as long as the session remains active).</TD></TR><TR><TD>
refresh</TD><TD>Maximum allowed time before the authentication info (perms and alike) are re-read from the database calling <CODE>auth_refreshlogin()</CODE> method. If set to 0 authentication info are read only at the login stage.</TD></TR><TR><TD>
mode</TD><TD>Authentication mode: <CODE>log</CODE> or <CODE>reg</CODE> (see below).</TD></TR><TR><TD>
database_class</TD><TD>A classname. Auth uses this class to make a database connection.</TD></TR><TR><TD>
database_table</TD><TD>Database table used to keep the session variables.</TD></TR><TR><TD>
magic</TD><TD>An arbitrary value used in uniqid generation.</TD></TR><TR><TD>
nobody</TD><TD>Flag: If true, we use default authentication.</TD></TR><TR><TD>
cancel&thinsp;login</TD><TD>The name of a button that can be used to cancel a login form</TD></TR><TR><TD>

<CAPTION>Accessible instance variables.</CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
db</TD><TD>Internal: The database connection object instance.</TD></TR><TR><TD>
auth</TD><TD>Internal: User authentication information, see below.</TD></TR><TR><TD>
in</TD><TD>Internal: Used in default authentication mode.</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>url()</B><DD><P>  
A function that can be used in <CODE>auth_loginform()</CODE>a and
<CODE>auth_registerform</CODE>. It returns the appropriate "action="
attribute to the form tag.
<P>
<DT><B>purl()</B><DD><P>  
A function that can be used in <CODE>auth_loginform()</CODE>a and
<CODE>auth_registerform</CODE>. It prints the appropriate "action="
attribute to the form tag.
<P>
<DT><B>login_if($t)</B><DD><P>A function that can be used to change the current user
identity. 
See the section and example on using default authentication
below.
<P>
<DT><B>unauth($nobody = false)</B><DD><P>This function destroys the authentication information in
<CODE>$this-&gt;auth</CODE>, forcing the user to relogin the next time
a protected page is being loaded.
<P><CODE>$this-&gt;auth["uname"]</CODE> is being kept, so that the
correct username is available as a default.
<P>Since V6: To give the user the credentials of `nobody', pass
true as the first parameter to unauth. This will also change
<CODE>$this-&gt;auth["uname"]</CODE>.
<P>Since V7.2: Passing $nobody to this method is deprecated.
<P>
<DT><B>logout($nobody = $this-&gt;nobody)</B><DD><P>This function destroy all authentication information
in  <CODE>$this-&gt;auth</CODE>, forcing the user to relogin
the next time a protected page is being loaded.
<P>Most applications want to use <CODE>$this-&gt;unauth()</CODE>
instead.
<P>Since V6: To give the user the credentials of `nobody', pass
true as the first parameter to logout. This defaults to the 
value you set in the class definition (<CODE>$nobody</CODE>).