Each class contains instance variables and instance methods. Some of these variables and methods are available for customization, some are internal to the classes themselves. All are documented, but tampering with internal variables and methods is not supported. Internal interfaces are subject to change without notice from one version of the library to another.
This section covers PHPLIB core functionality in reference form. Classes are presented in order of dependency, though, because the core structure is easier understood in this order. You will need to understand the complete core structure to successfully use all of PHPLIB's features.
DB_Sql is used by Session and Auth to access a
SQL database. You are encouraged to use it directly, too.
|
Host | Host where your SQL server is running on. |
| Database | Name of database or instance to use on that server. |
| User | The username used in connections attempts. |
| Password | The password used in connection attempts. |
| Row | Number of the current result row starting at 0. |
| Errno | Integer: error number of last database operation. |
| Error | String: error message of last database operation. |
| Autofree | In some DB interfaces a flag for early result memory release. |
|
|
|
Record | In some DB interfaces a hash of the current table result row. |
| Link_ID | SQL Link ID. |
| Query_ID | SQL Result ID. |
|
|
query_string is a SQL statement that is sent to the database.
After sending the statement, Error and Errno are updated.
If the query is syntactically incorrect (no valid result id is
being produced), halt() is called with a meaningful error
message.
If there is no active link to the database, a pconnect() is
made using the information from the Host, Database,
User and Password instance variables.
Returns the result of the query() statement, which is
guaranteed to be a valid result id.
next_record() advances the cursor through the
current query result and updates the Record, Row,
Errno and Error instance variables.
Returns true, if there is a new result record. Returns false, if
done with the current result set. If Autofree is true,
free_result() is called automatically before false
is returned.
Positions the Row pointer within the result set. Useful for
reading the same result set twice or otherwise jumping around
within the result. $pos is not checked in any way for
validity.
Note: If Autofree is true, seek() may not be
useable, because the result set has already been free'ed when
next_record() when behind the last record of the result
set.
$table is a SQL table name in the current database. The
function returns a hash indexed by table (table of which
this column is part of), name (name of this column),
type (column data type), len (column width) and
flags (database specific column flags, if applicable)
with one row per table column. Each row describes a column
in your table.
NOTE: At the moment, the PostgreSQL and ODBC interface only report
the table, name and type data reliably. You are
encouraged to fix this.
Returns the number of rows returned by the current SELECT query.
Returns the number of rows affected by the current INSERT, UPDATE or DELETE query.
Returns the number of columns returned by the current query.
Prints the number of rows returned by the current query.
Identical to accessing Record[$field].
Identical to printing Record[$field].
Used internally to generate a Link_ID, if necessary. Link
creation is implicit, there is no need to call connect()
manually, ever.
Used by query() if the initial database connection cannot
be made or the target database does not exist. Prints an
error message, then halts Script execution.
Use a subclass to provide the appropriate parameters for a
database connect. You may overwrite halt() to customize the
error message, although a sensible default is provided.
class DB_Article extends DB_Sql {
var $classname = "DB_Article";
var $Host = "sales.doma.in";
var $Database = "shop_project";
var $User = "webuser";
var $Password = "";
function halt($msg) {
printf("</td></table><b>Database error:</b> %s<br>\n", $msg);
printf("<b>MySQL Error</b>: %s (%s)<br>\n",
$this->Errno, $this->Error);
printf("Please contact shopmaster@doma.in and report the ");
printf("exact error message.<br>\n");
die("Session halted.");
}
}
Use an instance of the subclass to manage your queries:
$q = new DB_Article;
$query = sprintf("select * from articles where article like '%%%s%%'",
$searchword);
$q->query($query);
while($q->next_record()) {
printf("<tr><td>%s</td><td>%s</td></tr>\n",
$q->f("art_id"),
$q->f("article"));
}
PHP reuses connections, if possible. When a connection is being made to the same Host with the same Username and Password as an existing connection, no second connection is being made by PHP. Instead the existing connection is returned to the caller. This is true for both, the *_connect() and *_pconnect() calls of all PHP database interfaces.
This has implications for MySQL users: Never use the MySQL "use" command to change the current database. If you do, session management will fail to operate properly. Instead, create all PHPLIB tables as part of your application.
Some databases (for example Oracle) have very expensive connect() operations. For these databases, performance is dramatically improved if you switch from CGI PHP to mod_php. This is, because PHPLIB uses the "*_pconnect()" method to connect to your database. In mod_php, the database connection is kept around by the web server process after the page has been processed and is reused if a further connect requires a connection with the same Host/Username/Password pattern.
This means that there will be at most "number of web server processes" times "number of Host/Username/Password-combinations" many simultaneous connections to your database server. Keep that in mind when planning licenses and server load. Using CGI PHP will probably reduce the number of concurrent connects to your database server at the expense of connection setup time. For database servers where connection setup time is negligible (MySQL for example) this is a viable solution (don't try it with Oracle) though.
Page Management currently consists a collection of functions:
This function is to be called with an array of page features/classname pairs. Valid features are at the moment:
This page makes use of session variables.
This page uses session authentication. If you
specify the auth feature, you MUST specify
the sess feature, also.
This page is protected by permissions and only
accessible to authenticated users with matching rights.
If you specify the perm feature, you MUST specify
the auth and sess features, also.
This page makes use of user variables. If you specify
the user feature, you MUST specify the auth and
sess features, also.
Each feature specifies the name of the class that implements that feature, for example
page_open(array("sess" => "Shop_Session"));
The function creates an instance of Shop_Session as
$sess and initializes it. It also checks feature
dependencies. Note that you are expected to provide an
implementation of the class Shop_Session. This is
usually done in local.inc and usually you do so by
extending the provided Session class.
Examples on how to do this is given in the documentation below when the classes are introduced.
At the end of your page (after all results have been calculated)
you have to call page_close(). This will save all
page state, session and user variables into database. Changes to
session or user variables after page_close() has
been called are not recorded. Currently it is allowed to call
page_close() multiple times on a single page (not
guaranteed for future versions!). Each time session state will be
saved.
Note: This is going to change. When we introduce record
locking, it is important that you call page_close() only
once per page, because that will implicitly unlock your session
record. Also, it is important that you call page_close() as
early as possible on a page so that the locking time is kept
minimal.
Advanced feature. Some applications have need to manually load data belonging to one or multiple session classes. @@TODO
Advanced feature. @@TODO
<?php
page_open(array("sess" => "Shop_Session"));
$sess->register("s"); // See "Session" below for explanation.
?>
<html>
<h1><?php print ++$s ?></h1>
</html>
<?php page_close(); ?>
There used to be a feature "cart" for page_open() in
versions of PHPLIB up to release-5. The cart has been removed
from the core functionality of PHPLIB to keep the library small,
maintainable and structured. Consequently the "cart" feature is
gone.
The Cart class is still present and exists as an extended
feature. You have to include and instantiate your cart manually
on that pages that use it, though. See the Cart class for
more information.
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 database. 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.
|
classname | Serialization helper: The name of this class. |
| magic | A secret string used in ID creation. Change it! |
| mode | Mode of Session ID propagation. Either cookie or get. |
| fallback_mode | Mode of Session ID propagation should $mode not work. Set $mode to cookie and $fallback_mode to get. |
| lifetime | Lifetime of the session cookie in minutes or 0 to use session cookies. |
| gc_time | Garbage collection tuning parameter, see below. |
| gc_probability | Garbage collection tuning parameter, see below. |
| database_class | A classname. Session uses this class to make its database connection. |
| database_table | Database table used to keep the session variables. |
| auto_init | The file to be loaded on session establishment. |
| secure_auto_init | Set to 0, if all pages always callpage_close() (This is never the case!). |
|
|
|
pt | Internal array of names of persistent variables. |
| in | Flag: If set, auto_init has been executed. |
| name | A tag (name) for the session type. |
| id | Id of the current session. |
| db | Database connection object instance. |
|
|
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:
A string with the name of the objects class.
An array with the names of all object slots to save.
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.
Destroy the current session and put_id() the current session id.
After delete() has been executed, all session data has
been removed from the database. Also, the session object is
unusable on this page. Consequently, page_close() may
not be called for this session. Session variables are still
available on this page, even after the delete(), but
will be lost on the following pages.
In cookie mode, it is possible to page_open() a new
session after 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 page_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.
Return an URL referencing the current session. If in get
mode, the current session id is attached to this URL, else the
URL is returned unmodified.
A shorthand for print $this->url($url);
Return an URL referencing the current page, including
PHP_SELF and QUERY_STRING information.
If in get mode, the session id is included.
A shorthand for print $this->self_url().
When a FORM 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
FORM value is lost.
If you had enabled track_vars and were accessing
HTTP_GET_VARS directly, which is recommended,
this were not a problem. Some legacy scripts rely on persistent
FORM input variables, though.
These scripts may call the appropriate
reimport_x_vars() functions. These
functions will re-read the tracked variable arrays and
reinitialize the appropriate global variables after session
variables have been restored.
Use of this function is discouraged.
See reimport_get_vars().
See reimport_get_vars().
See get_id().
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.
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).
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).
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 not deleted.
serialize() is used internally to append to str all PHP code needed to reconstruct the variable named in prefix.
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.
thaw() loads a set of freeze()ed variables for the current session id and session name out of the database and recreates them.
The active_sessions table contains one row for
each session. That row is uniquely identified by the sid
and name values (name is the name of the session
class that has written the row). Each time that row is written,
the column changed is updated with the current time.
The gc() function deletes all rows that are older than
gc_time minutes and have a matching name
field. For speed reasons, gc() is not not called every time
an update to active_sessions is being made.
Instead it is called randomly with a probability of
gc_probability.
Used to implement the three official reimport functions.
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().
Use a subclass to provide the appropriate parameters to your session. Usually your subclass looks like this:
class My_Session extends Session {
var $classname = "My_Session"; ## Persistence support
var $mode = "cookie";
var $lifetime = 0; ## use session cookies
## DB_Sql subclass and database table to use
var $database_class = "DB_Session";
var $database_table = "active_sessions";
}
Remember that you have to provide a DB_Sql subclass
with the parameters needed to access your database.
Use the page management functions (see above) to use your
session subclass. The feature name for session management is
sess; provide the name of your session subclass as a
parameter to the sess feature:
page_open(array("sess" => "My_Session"));
Use the register() instance method to register variables as
persistent. If $sess is your session object, use
$sess->register("s");
to make the global variable $s persistent. $s may be a
scalar value, an array or an object with persistence support
slots.
Do not use the instance methods freeze() and thaw()
directly, but use the page management functions instead.
You may define $sess->auto_init to the name of an include
file in your extension of session. Per convention, the name
setup.inc is being used.
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.
}
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 page_open() function, that is,
not within a global context. To define or access global
variables from the auto_init file, you have to global them.
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 $sess, $auth, $perm and
$user variables, if your application specifies them.
Note 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 $auth object in general,
but have to test for it with is_object($auth) before
accessing it.
The auto_init file is the appropriate place to initialize and
register all your session variables. A sample setup.inc may
look like this:
<?php
global $lang; // application language
$lang = "de"; // german by default
$sess->register("lang");
global $cur; // application currency
$cur = "EUR"; // Euro by default
$sess->register("cur");
global $cart;
$cart = new Shop_Cart; // Create a shopping cart object as defined in local.inc
$sess->register("cart"); // register it.
?>
Note: 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 setup.inc for each page
they visit, too. Nothing can be done about this.
To get rid of a persistent variable, call
$sess->unregister() 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.
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 $sess->delete(). 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.
<?php
page_open(array("sess" => "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" => "Shop_Session")); // will force auto_init again!
$sess->register("user"); // could be done in auto_init as well
?>
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 name and
sid. name is the content of $this->name and
is usually the classname of your session class. sid is the
content of $this->id and is usually the MD5 hash of a
uniqid and some magic string.
By choosing a pair, it is possible for PHPLIB to have more than
one session type (for example, session and user data, see the
User class below) per application and store all this data
in a single table. If you are debugging a session class, for
example Poe_Session, only records where name =
"Poe_Session" are of interest to you. Determine the current
session id of your Poe_Session by printing $sess->id
and select the record with that name and sid from the
database.
The changed 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 changed
desc will show you the most current session records first (the
MySQL "limit" clause may come in handy here).
The val column of a session record contains a PHP program
that can be safely fed to stripslashes() first and
eval() 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.
First item is always an assignment to $this->in. If set
to 1, auto_init has been executed by this session. If
not set to 1, auto_init has not been executed, yet.
This may be because no auto_init file is defined for
that session.
After that comes code like this: $this->pt = array();
followed by a bunch of assignments like
$this->pt["somestring"] = 1;. Each somestring is the
name of a registered variable. Variable registrations are
persistent themselves and are saved with the $this->pt
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.
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
$GLOBALS[somevar] = "value";.
For an array, first $GLOBALS[someary] = array();
is generated. Then the scalars that make up the array, if any,
are written out, generating code that looks like
$GLOBALS[someary][index] = "value".
And for objects, code to create an object instance is saved:
$GLOBALS[someobj] = new Classname;. "Classname"
is taken from the objects $classname slot, which must
be present and accurate. Then the scalars that are to be saved
are written out, according to the contents of the objects
persistent_slots array:
$GLOBALS[someobj]->slot = "value"; is written.
If you want to see what values have been saved to the
database, you just have to look at the $GLOBALS assignments
for that session.
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.
The heart of the session class is the serialize() 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 $GLOBALS["a"] and the global variable $a
has the value 17, then serialize will create the PHP
program $GLOBALS["a"] = "17";. To save memory,
serialize() operates on a reference parameter $str,
where is will append the code generated.
First thing serialize() does is to determine the type of
the current expression using the PHP gettype() function.
The current type is stored in $t. The type of the
expression may indicate either a scalar value (integer number,
float number or string), an array or an object.
Scalar values are the easiest to handle: serialize() just
evaluates the current expression and remembers the result value
in $l. 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, serialize() ends here for
scalars.
In the case of $t indicating an array, code is generated to
create an empty array (expression = array();). Then the
keys of current expression are enumerated and for each key
serialize() is called recursively with the current key
appended to the expression. That will append code for each array
slot.
Should $t indicate an object, code is generated to create
that object (expression = new Classname;). Since one cannot
find out the name of the class of an object for arbitrary
objects in PHP, objects handled by serialize() must have a
slot named classname. The object handler will then
enumerate the contents of the objects slot persistent_slots
and call serialize() recursively for each of these slots
with the appropriate prefix.
Since many of the expressions used in serialize() require
variable variable names or even variable code, eval() is
used liberally. Unfortunately, this makes the code hard to read.
Authentication management can be used to authenticate a session, that is, to identify the user at the client side of the session.
Authentication is done inline, with HTML forms, not 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:
|
classname | Serialization helper: The name of this class. |
| persistent_slots | Serialization helper: The names of all persistent slots. |
| lifetime | Maximum allowed idle time before the authentication expires. |
| mode | Authentication mode: log or reg (see below). |
| database_class | A classname. Auth uses this class to make a database connection. |
| database_table | Database table used to keep the session variables. |
| magic | An arbitrary value used in uniqid generation. |
| nobody | Flag: If true, we use default authentication. |
|
|
|
db | Internal: The database connection object instance. |
| auth | Internal: User authentication information, see below. |
| in | Internal: Used in default authentication mode. |
|
|
A function that can be used in auth_loginform()a and
auth_registerform. It returns the appropriate "action="
attribute to the form tag.
A function that can be used in auth_loginform()a and
auth_registerform. It prints the appropriate "action="
attribute to the form tag.
A function that can be used to change the current user
identity from nobody in using default authentication mode.
See the section and example on using default authentication
below.
This function destroys the authentication information in
$this->auth, forcing the user to relogin the next time
a protected page is being loaded.
$this->auth["uname"] is being kept, so that the
correct username is available as a default.
Since V6: To give the user the credentials of `nobody', pass
true as the first parameter to unauth. This will also change
$this->auth["uname"].
This function destroy all authentication information
in $this->auth, forcing the user to relogin
the next time a protected page is being loaded.
Most applications want to use $this->unauth()
instead.
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 ($nobody).
logout() will call unauth() (passing $nobody),
so the behaviour is identical (except logout() will always
clear $this->auth["uname"] and unregister the auth class).
Will return false, if the current authentication is invalid or expired. Will return the authenticated uid otherwise.
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 include() statement to include
your HTML file.
This function is called when the user submits the login form
created by auth_loginform(). It must validate the user input.
If the user authenticated successfully, it must set up
several fields within the $auth[] instance variable:
must contain the user id associated with that user.
must contain the user name as entered by the user.
must not be tampered with (field is maintained by
start(), contains the time when the login expires).
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!)
See the example below for more information.
See auth_doregister().
These functions mirror auth_loginform() and
auth_validatelogin() in registration mode.
Initialization function, does the authentication. If we are
in log (login) mode, auth_loginform() is
called to draw a login screen. When the login screen is
submitted back, auth_validatelogin() is called to
validate the login. If the validation was successful, the
actual page content is shown, otherwise we're back at
auth_loginform().
In reg mode, auth_registerform() is called to draw a
registration form. When the registration form is submitted
back, auth_doregister() 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
auth_registerform().
Use a subclass of Auth to provide parameters for your
authentication class and to implement your own auth_* functions.
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->auth["uname"] set and use it.
$this->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->database_table,
addslashes($username),
addslashes($password)
);
$this->db->query($query);
## If we found a matching user, grab the uid and permissions...
while($this->db->next_record()) {
## Required.
$uid = $this->db->f("uid");
## Optional, for the perm feature.
$this->auth["perm"] = $this->db->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;
}
}
Your loginform.ihtml contains HTML and PHP code to draw a login
form. $this->auth["uname"] 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 $this->url() to
create your forms action attribute.
See the provided loginform.ihtml for an example.
Use the page management functions (see above) to use your
authentication subclass. The feature name for authentication
management is auth; provide the name of your Auth subclass as
a parameter to the auth feature. The auth feature requires the
sess feature:
page_open(array("sess" => "My_Session", "auth" => "My_Auth"));
Many applications want to use $auth and $perm
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 $auth and $perm objects to protect
functionality on a page, but you don't want a login screen to
appear by default.
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 nobody flag,
$auth will not create a login screen to force a user to
authenticate, but will authenticate the user silently as
nobody. The application must offer a login button or
other facility for users with accounts to change from that
id to their real user id.
To use default authentication, create a subclass of My_Auth
as shown above with the nobody flag set (Note: No need
to extend in two steps. The only important thing here is that
the nobody flag is set.)
class My_Default_Auth extends My_Auth {
var $classname = "My_Default_Auth";
var $nobody = true;
}
To create a page that uses default authentication, use the page
management functions. Check for relogin requests with the
login_if() function. Create a relogin link on your page.
<?php
// using Default Authentication
page_open(array("sess" => "My_Session", "auth" => "My_Default_Auth"));
$auth->relogin_if($again);
if ($auth->auth["uid"] == "nobody"):
?>
<A HREF="<?php pself_url() ?>?again=yes">Relogin</A>
to this page.
<?php endif ?>
As distributed, local.inc contains an example class
named Poe_Challenge_Auth, 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 Poe_Auth
always does.
Poe_Challenge_Auth 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 Auth with no
alteration of library code.
Poe_Challenge_Auth includes crloginform.ihtml. It
also requires that the file md5.js 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: $auth->auth_loginform() 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.
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.
The class is a dropin-replacement for Poe_Auth.
Permission management relies on an authenticated session. It associates a set of required permissions with a page. The actual page content is only visible to users with ALL matching permissions; all other users are shown a screen of your design.
|
classname | Serialization helper: The name of this class. |
| permissions | A hash of (name, permission bit) pairs. |
|
|
Checks that the currently authenticated user has all the
rights that are specified in required. If not,
perm_invalid() is called.
If one or more of the required rights or user rights are
invalid (not to be found in the permissions hash),
perm_invalid() is called as well.
Similar to check() in usage, only that it doesn't halt the
session if the user doesn't have the appropriate rights: This
function returns true, if the user has the required rights,
false otherwise.
This function returns a SELECT-tag with the given
name. Within this tag, all available permission values from
$perm->permissions are contained as OPTION tags.
If you supply a value for current, the permission value
that matches current is SELECTED. If you supply a
value for class, the tags are marked with that CSS
stylesheet class.
Logically or's all the rights and returns a pair (valid,
or_result). If valid is true, an or_result
is provided. If valid is false, the or_result is
undefined and one or more of the rights do not exist at all.
This is a severe error and the application should be halted at
once.
Called in case of an access violation. does_have is a string
listing the rights the user actually has. must_have are the
rights the page requires.
Use a subclass of Perm to provide parameters for your
permission class and to implement your own perm_invalid
function.
class My_Perm extends Perm {
var $classname = "My_Perm";
var $permissions = array (
"user" => 1,
"author" => 2,
"editor" => 4,
"moderator" => 8,
"admin" => 16
);
function perm_invalid($does_have, $must_have) {
global $perm, $auth, $sess;
include("perminvalid.ihtml");
}
}
Use the page management functions (see above) to use your
permission subclass. The feature name for permission
management is perm; provide the name of your Perm subclass as
a parameter to the perm feature. The perm feature requires the
sess feature and the auth feature:
page_open(array("sess" => "My_Session", "auth" => "My_Auth", "perm" => "My_Perm"));
Use the check() instance method to protect your page:
$perm->check("admin"); ## This page is for users with admin rights only.
Use have_perm() to create protected functionality on a
page:
<?php
if ($perm->have_perm("admin"):
?>
<h1>Admin only functionality</h1>
<?php
endif;
?>
Your subclass of Perm defines an array $permissions,
which translates permission names into bit patterns. For
example, the definition of Poe_Perm in the distributed
local.inc defines the names user, author,
editor, supervisor and admin, all of which
translate into a bit pattern with a single bit set.
A user may be assigned any number of permissions as a comma
separated list of permission names (no spaces!) in the
perms column of the auth_user table. The effective
permissions of the user are determined by logically OR'ing the
bit patterns of these permissions.
A page may require any permissions as a comma separated list of
permission names (again no spaces!) with the
$perm->check() function. The required permissions are
again determined by logically OR'ing the bit patterns of these
permissions. Similarly, a page function may be protected by
requiring permissions with $perm->check().
Access is granted to a protected page or a protected page function, if the effective permissions of the authenticated user have all the required bits set, that is: If the effective permissions of the user logically AND'ed with the required permissions are equal to the required permissions.
With the permission names as defined in Poe_Perm from the
distribution, a user kris may be defined with admin
permission in the auth_user table. A page that requires
admin,user permission with
$perm->check("user,admin") is inaccessible to this user.
This is how it is calculated:
Effective Permissions of User: admin
translates into: 16
Required Permissions of Page : user,admin
translates into: 1 OR 16 == 17
Permission Check:
Effective Permissions 16
AND Required Permissions 17
ARE 16 & 17 = 16
MUST BE Required Permissions 17 -> access denied
The example permissions as defined in Poe_Perm from the
distribution are called atomic permissions, because each of
them has only a single bit set. Atomic permissions are the
simplest of all schemes, because they allow for easy permission
checks: To access a page protected with user,admin, you
need to have at least user,admin rights in your
auth_user table.
Another common scheme used in permission definitions are
inclusive permissions. In this scheme, each permission
definition has all bits of its predecessor set plus one addition
bit. For example
class Inclusive_Perm extends Perm {
var $classname = "Inclusive_Perm";
var $permissions = array(
"user" => 1,
"author" => 3,
"editor" => 7,
"supervisor" => 15,
"admin" => 31
);
}
defines a set of inclusive permissions. In this example, a user
kris with admin permissions can easily access a page
protected with editor permissions. This is how it is
calculated:
Effective Permissions of User: admin
translates into: 31
Required Permissions of Page : editor
translates into: 7
Permission Check:
Effective Permissions 31
AND Required Permissions 7
ARE 31 & 7 = 7
MUST BE Required Permissions 7 -> access granted
Inclusive Permissions are easy to deal with, too, because a user with a higher access level may access all pages or page functions with a lower access level.
Due to limitations of your machines integer size you can only define up to 31 permission levels.
The user class is an extension (a subclass) of the Session class. It keeps a list of global variable names and provides a set of functions to load and save these variables from and to a database. The same restrictions as for session variables apply to user variables.
Unlike session variables, user variables are not lost when the user stops and restarts the browser or moves to a different workplace (the session id is then lost and consequently all session variables are lost, since they are bound to the session id).
User variables require that the user logs in, because they depend on the availability of a User id to bind variables to this id. Thus, User is dependent on Auth.
The User class is an extension of the Session class. It has all instance variables and instance methods of Session, only that some are implemented different. This documentation only describes these differences.
Note that Session and User can successfully share a single
active_sessions table in a database due to the
different values in the name column.
|
classname | Serialization helper: The name of this class.magic | Not meaningful for User. |
| mode | Not meaningful for User. | |
| fallback_mode | Not meaningful for User. | |
| lifetime | Not meaningful for User; see authentication lifetime in Auth instead. | |
| gc_time | Functional, but probably not useful in User. | |
| gc_probability | Functional, but should be set to 0 in User. | |
| database_class | A classname. User uses this class to make its database connection. | |
| database_table | Database table used to keep the user variables. | |
| auto_init | Not meaningful for User. | |
| secure_auto_init | Not meaningful for User. | |
|
|
|
pt | Internal array of names of persistent variables. |
| name | A tag (name) for the session type. |
| id | Id of the current session. |
| db | Database connection object instance. |
|
|
Works as expected.
Works as expected.
Works as expected.
Not useful with User.
Not useful with User.
Not useful with User.
Not useful with User.
Works as expected.
Works as expected.
Works as expected.
This is only a stub implementation that depends on
the user id provided by the page management functions.
The page management functions will use
$auth->auth["uid"], which is set up by Auth.
Empty. Not useful with User.
Works as expected.
Works as expected.
Works as expected.
Works as expected. You do not want to use it, though.
Works as expected.
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. Note: gc() activation is commented out! Remove the comments if you really want gc with User variables.
Use a subclass to provide the appropriate parameters to your user variables. Usually your subclass looks like this:
class My_User extends User {
var $classname = "My_User"; ## Persistence support
## DB_Sql subclass and database table to use
var $database_class = "DB_Session";
## We share this table with My_Session - not a problem.
var $database_table = "active_sessions";
}
Remember that you have to provide a DB_Sql subclass with the
parameters needed to access your database.
Use the page management functions (see above) to use your
User subclass. The feature name for user variables is
user; provide the name of your User subclass as a parameter
to the user feature:
page_open(array("sess" => "My_Session", "auth" => "My_Auth", "user" => "My_User"));
Use the register() instance method to register variables as
persistent. If $user is your user object, use
$user->register("u");
to make the global variable $u persistent. $u may be a
scalar value, an array or an object with persistence support
slots.
Do not use the instance methods freeze() and thaw()
directly, but use the page management functions instead.
Note: Using default authentication and user variables is
going to be a problem, because currently User does not do
any locking. This is, because the DB_Sql has currently no
portable locking mechanism.