documentation-3.html

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

<CODE>logout()</CODE> will call <CODE>unauth()</CODE> (passing <CODE>$nobody</CODE>),
so the behaviour is identical (except <CODE>logout()</CODE> will always
clear <CODE>$this-&gt;auth["uname"]</CODE> and unregister the auth class).
<P>Since V7.2: Passing $nobody to this method is deprecated.
<P>
<DT><B>is_authenticated()</B><DD><P>Will return false, if the current authentication is
invalid or expired. Will return the authenticated uid
otherwise.
<P>
<DT><B>auth_preauth()</B><DD><P>This function can be overridden in a subclass to Auth. It
is being called as the very first step in the authentication
process and has the opportunity to authenticate the user
without a loginform being displayed (by deriving all necessary
information telepathically, or by using cookies, or divining
the user identities from the incestines of a dead squirrel).
<P>If it returns a UID value, the user is authenticated and neither
auth_loginform() nor auth_validatelogin() are
called. If it returns false, all goes on as usual.
<P>
<DT><B>auth_loginform()</B><DD><P>  
This function must be overridden by a subclass to Auth. It
should output HTML that creates a login screen for the user.
We recommend that you use an <CODE>include()</CODE> statement to include
your HTML file.
<P>
<DT><B>auth_validatelogin()</B><DD><P>This function is called when the user submits the login form
created by <CODE>auth_loginform()</CODE>. It must validate the user input.
<P>If the user authenticated successfully, it must set up
several fields within the <CODE>$auth[]</CODE> instance variable:
<P>
<DL>
<DT><B>"uid"</B><DD><P>must contain the user id associated with that user.
<DT><B>"uname"</B><DD><P>must contain the user name as entered by the user.
<DT><B>"exp"</B><DD><P>must not be tampered with (field is maintained by
<CODE>start()</CODE>, contains the time when the login expires).
<DT><B>"perm"</B><DD><P>if you want to use the permission feature, you
must store the permissions of the validated user here.
(Hint: due to a name conflict with sybase, "perm" is called "perms"
in all the databases tables. Look for this small difference!)
</DL>
<P>See the example below for more information.
<P>
<DT><B>auth_refreshlogin()</B><DD><P>This function is called every <CODE>refresh</CODE> minutes. It must refresh
the authentication informations stored in <CODE>auth</CODE> array by
<CODE>auth_validatelogin()</CODE> method. It is not called if the
user is logged in as nobody.
<P>It must return true on success, false otherwise (i.e.: the userid
is no longer valid).
<P>
<DT><B>auth_registerform()</B><DD><P>See auth_doregister().
<P>
<DT><B>auth_doregister()</B><DD><P>These functions mirror <CODE>auth_loginform()</CODE> and
<CODE>auth_validatelogin()</CODE> in registration mode.
</DL>
<P>
<H3>Internal instance methods</H3>

<P>
<P>
<DL>
<DT><B>start()</B><DD><P>
<P>Initialization function, does the authentication. If we are
in <CODE>log</CODE> (login) mode, <CODE>auth_loginform()</CODE> is
called to draw a login screen. When the login screen is
submitted back, <CODE>auth_validatelogin()</CODE> is called to
validate the login. If the validation was successful, the
actual page content is shown, otherwise we're back at
<CODE>auth_loginform()</CODE>.
<P>In <CODE>reg</CODE> mode, <CODE>auth_registerform()</CODE> is called to draw a
registration form. When the registration form is submitted
back, <CODE>auth_doregister()</CODE> is called to register the user and
to validate the session. If registration was successful, the
actual page content is shown, otherwise we're back at
<CODE>auth_registerform()</CODE>.
</DL>
<P>
<H3>Example</H3>

<P>Use a subclass of <CODE>Auth</CODE> to provide parameters for your
authentication class and to implement your own <CODE>auth_*</CODE> functions.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Auth extends Auth {
  var $classname        = "My_Auth"; # Object serialization support

  var $lifetime         =  15;
  
  ## DB_Sql subclass and database table to use
  var $database_class = "DB_Session";
  var $database_table = "auth_user";

  ## Some magic value to make our uids harder to guess.
  var $magic = "Abracadabra";

  ## Use an own login form
  function auth_loginform() {
    global $sess;
    include("loginform.ihtml");
  }
  
  function auth_validatelogin() {
    global $username, $password;    ## form variables from loginform.ihtml
    
    ## If authentication fails, loginform.html will
    ## find $this-&gt;auth["uname"] set and use it.
    $this-&gt;auth["uname"]=$username;
    
    ## Value to return in case auth fails.
    $uid   = false;
    
    ## Check the database for this user and password pair.
    $query = sprintf(
      "select * from %s where username = '%s' and password = '%s'",
      $this-&gt;database_table,
      addslashes($username),
      addslashes($password)
    );
    $this-&gt;db-&gt;query($query);
    
    ## If we found a matching user, grab the uid and permissions...
    while($this-&gt;db-&gt;next_record()) {
      ## Required.
      $uid = $this-&gt;db-&gt;f("uid");
      
      ## Optional, for the perm feature.
      $this-&gt;auth["perm"] = $this-&gt;db-&gt;f("perms");
      ## if you use perm feature be aware, that the db-field in our
      ## example table is called "perms" due to a name conflict with sybase
    }
    
    return $uid;
  }
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>Your <CODE>loginform.ihtml</CODE> contains HTML and PHP code to draw a login
form. <CODE>$this-&gt;auth["uname"]</CODE> will be empty on the first login
attempt and set on all further login attempts. You can use this
to detect repeated login attempts and display an appropriate
error message. You must print the result of <CODE>$this-&gt;url()</CODE> to
create your forms action attribute.
<P>See the provided <CODE>loginform.ihtml</CODE> for an example.
<P>Use the page management functions (see above) to use your
authentication subclass. The feature name for authentication
management is <CODE>auth</CODE>; provide the name of your <CODE>Auth</CODE> subclass as
a parameter to the <CODE>auth</CODE> feature. The <CODE>auth</CODE> feature requires the
<CODE>sess</CODE> feature:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
  page_open(array("sess" =&gt; "My_Session", "auth" =&gt; "My_Auth"));
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Using default authentication</H3>

<P>Many applications want to use <CODE>$auth</CODE> and <CODE>$perm</CODE>
objects to protect functionality on a page, but do want to
make the unprotected part of this page available to users
with no account. This presents a kind of dilemma, because you
need <CODE>$auth</CODE> and <CODE>$perm</CODE> objects to protect
functionality on a page, but you don't want a login screen to
appear by default.
<P>Default authentication solves this dilemma by providing a
special uid and uname "nobody", which is guaranteed to fail
every permission check. If you set the <CODE>nobody</CODE> flag,
<CODE>$auth</CODE> will not create a login screen to force a user to
authenticate, but will authenticate the user silently as
<CODE>nobody</CODE>. The application must offer a login button or
other facility for users with accounts to change from that
id to their real user id.
<P>To use default authentication, create a subclass of <CODE>My_Auth</CODE>
as shown above with the <CODE>nobody</CODE> flag set (<EM>Note:</EM> No need
to extend in two steps. The only important thing here is that
the <CODE>nobody</CODE> flag is set.)
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
class My_Default_Auth extends My_Auth {
  var $classname = "My_Default_Auth";

  var $nobody = true;
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>To create a page that uses default authentication, use the page
management functions. Check for relogin requests with the
<CODE>login_if()</CODE> function. Create a relogin link on your page.
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
  // using Default Authentication
  page_open(array("sess" =&gt; "My_Session", "auth" =&gt; "My_Default_Auth"));
  $auth-&gt;login_if($again);

  if ($auth-&gt;auth["uid"] == "nobody"):
?&gt;
  &lt;A HREF="&lt;?php $sess-&gt;purl("$PHP_SELF?again=yes") ?&gt;"&gt;Relogin&lt;/A&gt;
  to this page.
&lt;?php endif ?&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>Using Challenge-Response Authentication</H3>

<P>As distributed, <CODE>local.inc</CODE> contains an example class
named <CODE>Example_Challenge_Auth</CODE>, which uses a
Challenge-Response authentication scheme. If the client
browser supports Javascript, this login screen does not
transmit passwords in clear over the network. If the client
does not support Javascript, login is still possible, but
passwords are transmitted in clear, as regular <CODE>Example_Auth</CODE>
always does.
<P><CODE>Example_Challenge_Auth</CODE> is there to demonstrate advanced
usage of PHP and Javascript and to show off the flexibility
of the library base classes: The Challenge-Response
authentication scheme has been implemented completely and
naturally in local.inc by subclassing <CODE>Auth</CODE> with no
alteration of library code.
<P><CODE>Example_Challenge_Auth</CODE> includes <CODE>crloginform.ihtml</CODE>. It
also requires that the file <CODE>md5.js</CODE> is present in the
document root directory of your web server. That file contains
an implementation of the MD5 message digest algorithm done by
Henri Torgemane. The basic idea behind this authentication
scheme is simple: <CODE>$auth-&gt;auth_loginform()</CODE> creates a
challenge value which is incorporated into this form. When
the user tries to submit the form,
MD5("username:password:challenge") is calculated and filled
into the reply field. The password field is erased. The
server can calculate the expected reply from the username
received, the password in the database and the challenge,
which it knows. It can compare the expected reply to the
actual reply value. If they match, the user is authenticated.
<P>If the reply field is empty and password is set, the server
knows that the client cannot do Javascript. The user can still be
authenticated, but the password is visible on the network.    
<P>The class is a dropin-replacement for <CODE>Example_Auth</CODE>.
<P>
<H3>The complete guide to authentication and user variables</H3>

<P>
<P>This feature has originally been written for the PHPLIB mailing
list by Kristian K鰄ntopp and was included into the
documentation later.
<P>
<H3>How is the <CODE>Auth</CODE> class used usually?</H3>

<P>
<P>Usually, you write code like this into the top of the page you
want to protect:
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
&lt;?php
page_open(array(
    "sess" =&gt; "My_Session", 
    "auth" =&gt; "My_Auth"));
?&gt;

&lt;!-- your code here --&gt;

&lt;?php
page_close()
?&gt;
</PRE>
<HR>
</CODE></BLOCKQUOTE>
<P>
<H3>How does <CODE>$auth</CODE> work internally?</H3>

<P>
<P>When you access this page, the call <CODE>to page_open()</CODE> is being
made as the first thing on that page. <CODE>page_open()</CODE> creates
an instance of <CODE>My_Auth</CODE> named <CODE>$auth</CODE> and starts it.
<CODE>$auth</CODE> then detects that you are not authenticated (how it
does, I will explain below) and displays <CODE>loginform.ihtml</CODE>.
$auth then exits the interpreter, so that &lt;!-- your code here
--&gt; is never being executed or displayed.
<P>The user now sits in front of a <CODE>loginform.ihtml</CODE> screen,
which is shown under the URL of the page the user originally
tried to access. The loginform has an action URL, which just
points back to itself.
<P>When the user filled out the loginform and submits it, the very
same URL is requested and the above <CODE>page_open()</CODE> is
reexecuted, but this time a username and a password are
submitted. When the <CODE>$auth</CODE> object is created and started, it
detects these parameters and validates them, resulting in either
a NULL value or a valid user id. If the validation failed,
creating an empty user id, the loginform is displayed again and
the interpreter exits. Again &lt;!-- your code here --&gt; is not
executed.
<P>If a UID is returned, that UID and a timestamp are being made
persistent in that session and <CODE>$auth</CODE> returns control to
<CODE>page_open()</CODE>. When <CODE>page_open()</CODE> finishes, which it may
or may not do, depending on the presence and result of an
optional <CODE>$perm</CODE> check, &lt;!-- your code here --&gt; is being
executed or shown.
<P>Later calls to other pages or the same page check for the
presence of the UID and the timestamp in the sessions data. If
the UID is present and the timestamp is still valid, the UID is
retained and the timestamp is refreshed. On <CODE>page_close()</CODE>
both are written back to the user database (Note: Authenticated
pages REQUIRE that you <CODE>page_close()</CODE> them, even when you
access them read-only or the timestamp will not be refreshed).
<P>If