3. Core Functionality

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.

3.1 DB_Sql

DB_Sql is used by CT_Sql and Auth to access a SQL database. You are encouraged to use it directly, too.

Instance variables

Instance methods

Accessible instance methods

DB_Sql($query = "")

Constructor. When creating an instance, you may optionally supply a query string.

---

$db = new DB_Sql_Subclass("select * from mytable");)

---

query($query_string)

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 (or false, if Halt_On_Error isn't "yes").

next_record()

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 Auto_Free is true, free_result() is called automatically before false is returned.

num_rows(), nf()

Returns the number of rows returned by the current SELECT query.

Note: This information is not available in all database interfaces. Some of the more advanced databases begin to return query results asynchronously while the backend is still appending result rows. In such environments the complete size of the result set is never known.

You should duplicate your WHERE clause of the query in such environments and ask for the COUNT(*). This will be less inefficient as it seems as the query path and query result have been cached by the database.

affected_rows()

Returns the number of rows affected by the current INSERT, UPDATE or DELETE query.

num_fields()

Returns the number of columns returned by the current query.

np()

Prints the number of rows returned by the current query.

f($field)

Identical to accessing Record[$field].

p($field)

Identical to printing Record[$field].

haltmsg($msg)

This function is called by halt() and will actually print the database error message. You may override this method in your subclass of DB_Sql and format the error message to be consistent with the layout of the rest of your application. You may also add additional error handling such as informing the application operator by mail that a database error has occured.

seek($pos)

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 Auto_Free 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.

Note: Not all database interfaces provide a cursor that is capable of seeking. This function will be unavailable in such environments.

link_id()

This function will return the current link ID, as returned by the pconnect() executed internally by the database class.

You should not need this information.

query_id()

This function will return the current result ID, as returned by the query() executed internally by the database class.

You should not need this information.

metadata($table = "", $full = false)

$table is a SQL table name in the current database. The function returns an array of hashes indexed on the (0 based) column number of $table. Each hash is 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.

The data returned by metadata() is suitable for passing it to the Table class. If you specify the full parameter, an additional column meta is added, which is indexed by field name and returns the field number of that name. Also, a column num_fields is added, containing the width of the table.

If $table is omitted, the function returns metadata on the result of the last executed query. Note: This is currently implemented only for the MySQL interface. You are encouraged to implement this feature for other interfaces.

NOTE: At the moment, the PostgreSQL and ODBC interface only report the table, name and type data reliably. You are encouraged to fix this.

table_names()

Returns an array with table name and tablespace name.

---

table name      : $return[$i]["table_name"]
tablespace_name : $return[$i]["tablespace_name"]

---

Tables are from $i=0 to last table;

Implemented in db_oracle.inc,db_oci8.inc,db_mysql.inc,db_pgsql.inc

nextid($sequence_name)

This function will return a sequence number from the sequence named by $sequence_name. This number is guaranteed to be obtained in an atomic manner and can be used as a primary key.

Internal instance methods

connect()

Used internally to generate a Link_ID, if necessary. Link creation is implicit, there is no need to call connect() manually, ever.

halt($msg)

Used by query() if the initial database connection cannot be made or the target database does not exist. Depending on the setting of Halt_On_Error, this method will call haltmsg() to report the error.

free()

Used internally by next_record() to free the result set, if so configured.

Example

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 haltmsg($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");
  }
}

---

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"));
}

---

Additional information about database connections

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.

Using nextid()

The nextid() function can be used to obtain a sequence number which can be used as a primary key. The function manages an arbitrary number of named sequences, you have to provide the name of a sequence upon call.

---

$db = new DB_Article;

$artnr = $db->nextid("article_sequence");
$query = sprintf("insert into articles ( artnr, ...) values ('%s', ...)", 
   $artnr, ...);
$db->query($query);

reset($articles);
while(list($itemnr, $itemdesc) = each($articles)) {
  $itemnr = $db->nextid("item_sequence");
  $query = sprintf("insert into items (artnr, itemnr, ...) values ('%s', '%s', ...)",
    $artnr, $itemnr, ...);
  $db->query($query);
}

---

3.2 Page Management

Accessible Functions

Page Management currently consists a collection of functions:

page_open(array("feature" => "classname"))

This function is to be called with an array of page features/classname pairs. Valid features are at the moment:

sess

This page makes use of session variables.

auth

This page uses session authentication. If you specify the auth feature, you MUST specify the sess feature, also.

perm

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.

user

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.

page_close()

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.

sess_load(array("var" => "classname")

Advanced feature. Some applications have need to manually load data belonging to one or multiple session classes. @@TODO

sess_save(array("var" => "classname"))

Advanced feature. @@TODO

Example

---

<?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(); ?>

---

The "cart" feature is gone

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.

3.3 CT_Sql

The Session class used to contain a bit of SQL to read and write session data from and to a database. To make sessions database independent, this SQL has been isolated and put in a separate class, CT_Sql. Session now makes all storage accesses through a container class, which may or may not be an SQL container.

Instance variables

Example

Use a subclass to provide the appropriate parameters to your container. Usually your subclass looks like this:

---

class My_Sql extends CT_Sql {
        var $classname = "My_Sql";
        var $database_table = "active_sessions";
        var $database_class = "DB_Session";
}

---

You can then use My_Sql in class Session. Reference it by putting "My_Sql" in the "that_class" variable.

3.4 CT_Split_Sql

The Session class used to contain a bit of SQL to read and write session data from and to a database. To make sessions database independent, Session now makes all storage accesses through a container class. The CT_split_sql container is very similar to CT_Sql container, with the difference that if serialized data exceeds a specified amount of bytes, multiple rows will be used to memorized the entire field.

This class is NOT compatible with CT_Sql class, since table layout is different and column names are different in order to avoid reserved words in various database implementation. This uses a DB_Sql like class so you can access all supported databases with this container.

Instance variables

Example

Use a subclass to provide the appropriate parameters to your container. Usually your subclass looks like this:

---

class My_Sql extends CT_Split_Sql {
        var $classname = "My_Sql";
        var $database_table = "active_sessions_split";
        var $database_class = "DB_Session";
        var $split_length = 4096;
}

---

You can then use My_Sql in class Session. Reference it by putting "My_Sql" in the "that_class" variable.

3.5 CT_Shm

The Session class used to contain a bit of SQL to read and write session data from and to a database. To make sessions database independent, Session now makes all storage accesses through a container class. To let Session use shared memory as container, you use CT_Shm.

Instance variables

Example

Use a subclass to provide the appropriate parameters to your container. Usually your subclass looks like this:

---

class My_Shm extends CT_Shm {
        var $classname = "My_Shm";
        var $max_sessions = 500;
        var $shm_key = 0x1234232;
        var $shm_size = 64000;
}

---

You can then use My_Shm in class Session. Reference it by putting "My_Shm" in the "that_class" variable.

3.6 CT_Dbm

The Session class used to contain a bit of SQL to read and write session data from and to a database. To make sessions database independent, Session now makes all storage accesses through a container class. To let Session use a DBM database file as a container, you use CT_Dbm.

Instance variables

Example

Use a subclass to provide the appropriate parameters to your container. Usually your subclass looks like this:

---

class My_Dbm extends CT_Dbm {
        var $dbm_file = "data/session.dbm";
}

---

You can then use My_Dbm in class Session. Reference it by putting "My_Dbm" in the "that_class" variable.

3.7 CT_Ldap

The Session class used to contain a bit of SQL to read and write session data from and to a database. To make sessions database independent, Session now makes all storage accesses through a container class. To let Session use a LDAP database as a container, you use CT_Ldap.

Instance variables

Example

Use a subclass to provide the appropriate parameters to your container. Usually your subclass looks like this:

---

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";
}

---

You can then use My_Ldap in class Session. Reference it by putting "My_Ldap" in the "that_class" variable.

3.8 Session

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.

Instance variables

Instance methods

Accessible instance methods

register($varname)

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:

classname

A string with the name of the objects class.

persistent_slots

An array with the names of all object slots to save.

unregister($varname)

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.

is_registered($varname)

Returns true if the variable named $varname is registered with the session, false otherwise.

delete()

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.

url($url)

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.

purl($url)

A shorthand for print $this->url($url);

self_url()

Return an URL referencing the current page, including PHP_SELF and QUERY_STRING information. If in get mode, the session id is included.

pself_url()

A shorthand for print $this->self_url().

hidden_session()

Adds a hidden form element containing the session name and id.

add_query($qarray)

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

---

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

---

padd_query($qarray)

A shorthand for print $this-> add_query($qarray).

reimport_get_vars()

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.

reimport_post_vars()

See reimport_get_vars().

reimport_cookie_vars()

See reimport_get_vars().

set_container()

You shall not call this function directly. It is called back by the start() function of Session() during initializiation. It is documented so that you can override its implementation in your subclass of Session if you know what you are doing.

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

set_tokenname()

You shall not call this function directly. It is called back by the start() function of Session() during initializiation. It is documented so that you can override its implementation in your subclass of Session if you know what you are doing.

This function determines and sets the internal session name.

release_token()

You shall not call this function directly. It is called back by the start() function of Session() during initializiation. It is documented so that you can override its implementation in your subclass of 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.

put_headers()

You shall not call this function directly. It is called back by the start() function of Session() during initializiation. It is documented so that you can override its implementation in your subclass of 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.

Internal instance methods

get_id()

See get_id().

get_id($id_to_use)

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()

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($prefix, &$str)

serialize() is used internally to append to str all PHP code needed to reconstruct the variable named in prefix.

freeze()

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()

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

gc()

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.

reimport_any_vars($arrayname)

Used to implement the three official reimport functions.

start()

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 allowcache to send proper headers to control browser caching.

Example

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
  
  ## which container to use
  var $that_class = "Session_sql";
}

---

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.

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

---

class My_Cached_Session extends My_Session {
  ## pages that use this session instance are cached.
  var $allowcache = "private";
}

---

Be careful when using the public cache option. Publically cached pages may be accessible to unauthenticated users. The private cache option prevents unauthenticated access, but is only functional in HTTP/1.1 browsers.

Using "auto_init"

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.

Unregistering variables and deleting sessions

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

?>

---

Reading and understanding session data for debugging

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 Example_Session, only records where name = "Example_Session" are of interest to you. Determine the current session id of your Example_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.

How "serialize()" operates

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.

3.9 Auth

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:

• It can be undone: A session can be un-authenticated, the user can "log out".
• It can expire: A session can automatically be un-authenticated after a given idle time.
• 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.
• It is database based. Authentication is being done against a database of your design, not a htpasswd text file.
• It is per page. You decide on a per-page basis which pages are authenticated and which aren't.
• It can be user authenticating and optionally self registering. In registration mode, a user without a valid login is encouraged to register and an account is created for this user.
• It works with CGI PHP. HTTP authentication is available only in mod_php.
• It is integrated with a permission checking scheme.

Instance variables

Instance methods

Accessible instance methods

url()

A function that can be used in auth_loginform()a and auth_registerform. It returns the appropriate "action=" attribute to the form tag.

purl()

A function that can be used in auth_loginform()a and auth_registerform. It prints the appropriate "action=" attribute to the form tag.

login_if($t)

A function that can be used to change the current user identity. See the section and example on using default authentication below.

unauth($nobody = false)

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"].

Since V7.2: Passing $nobody to this method is deprecated.

logout($nobody = $this->nobody)

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).

Since V7.2: Passing $nobody to this method is deprecated.

is_authenticated()

Will return false, if the current authentication is invalid or expired. Will return the authenticated uid otherwise.

auth_preauth()

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).

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.

auth_loginform()

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.

auth_validatelogin()

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:

"uid"

must contain the user id associated with that user.

"uname"

must contain the user name as entered by the user.

"exp"

must not be tampered with (field is maintained by start(), contains the time when the login expires).

"perm"

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.

auth_refreshlogin()

This function is called every refresh minutes. It must refresh the authentication informations stored in auth array by auth_validatelogin() method. It is not called if the user is logged in as nobody.

It must return true on success, false otherwise (i.e.: the userid is no longer valid).

auth_registerform()

See auth_doregister().

auth_doregister()

These functions mirror auth_loginform() and auth_validatelogin() in registration mode.

Internal instance methods

start()

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().

Example

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"));

---

Using default authentication

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->login_if($again);

  if ($auth->auth["uid"] == "nobody"):
?>
  <A HREF="<?php $sess->purl("$PHP_SELF?again=yes") ?>">Relogin</A>
  to this page.
<?php endif ?>

---

Using Challenge-Response Authentication

As distributed, local.inc contains an example class named Example_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 Example_Auth always does.

Example_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.

Example_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 Example_Auth.

The complete guide to authentication and user variables

This feature has originally been written for the PHPLIB mailing list by Kristian Köhntopp and was included into the documentation later.

How is the Auth class used usually?

Usually, you write code like this into the top of the page you want to protect:

---

<?php
page_open(array(
    "sess" => "My_Session", 
    "auth" => "My_Auth"));
?>

<!-- your code here -->

<?php
page_close()
?>

---

How does $auth work internally?

When you access this page, the call to page_open() is being made as the first thing on that page. page_open() creates an instance of My_Auth named $auth and starts it. $auth then detects that you are not authenticated (how it does, I will explain below) and displays loginform.ihtml. $auth then exits the interpreter, so that <!-- your code here --> is never being executed or displayed.

The user now sits in front of a loginform.ihtml 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.

When the user filled out the loginform and submits it, the very same URL is requested and the above page_open() is reexecuted, but this time a username and a password are submitted. When the $auth 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 <!-- your code here --> is not executed.

If a UID is returned, that UID and a timestamp are being made persistent in that session and $auth returns control to page_open(). When page_open() finishes, which it may or may not do, depending on the presence and result of an optional $perm check, <!-- your code here --> is being executed or shown.

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 page_close() both are written back to the user database (Note: Authenticated pages REQUIRE that you page_close() them, even when you access them read-only or the timestamp will not be refreshed).

If the UID is not present ($auth->logout() or $auth->unauth() have been called, for example) or the timestamp has expired, $auth will again intercept page display and draw the loginform.

The only way to get into a page with an $auth object on it is to have a UID and a valid timestamp in your session data (Note: This is true even for default authentication. These create a dummy UID and timestamp in your session data).

How do $sess and $auth interact?

Your browser has a session cookie, named after your session class. This is the only thing that is ever shipped between your browser and PHPLIB, as far as core functionality is concerned. The session cookie value is used as a reference into active_sessions, to retrieve PHPLIB generated PHP code, which is then eval()ed and recreates your session variables within page_open().

Part of the $auth object now makes itself persistent and is retrieved when the $sess part of page_open() is being executed. This is just before the $auth part of page_open() gets its turn, so that $auth can rely on its persistent data being present when it is being called.

From the PHPLIB source you all know that $auth has only one persistent slot, called $auth->auth[], of type hash. This hash contains the slots uid, exp and uname. $auth->auth["uid"] is the currently authenticated user id, $auth->auth["exp"] is the currently active expiration timestamp (Unix time_t format) for that uid. $auth->auth["uname"] is completely irrelevant as far as the regular PHPLIB Auth class is concerned. It is relevant in the context of the supplied default Auth subclass Example_Auth, though.

So a session is authenticated, if it contains $auth->auth["uid"] != false and time() < $auth->auth["exp"].

Where is the beef?

The original Auth class as included in PHPLIB makes no assumptions at all on how a loginform looks or how and where uids come from. There is no code at all in Auth that ever checks anything but the above two conditions. It is your responsibility to modifiy a subclass of Auth in a way that these conditions can ever be met.

Auth helps you in doing this by calling its own function $auth->auth_loginform() when it wants to draw a loginform. Unfortunately this function is empty in Auth itself, so you have to provide an implementation for that. The suggested standard implementation in local.incs Auth subclass Example_Auth is

---

function auth_loginform() {
  include("loginform.ihtml");
}

---

and you put your code into that file. We also provide sample code for that file, but you are not limited to that code and may write a loginform.ihtml as it meets your needs.

When the loginform has been filled in and submitted back by the user, Auth calls $auth->auth_validatelogin(). Again, this function is empty in Auth itself and so Auth by itself will never function correctly. You have to subclass Auth and provide your own implementation of $auth->auth_validatelogin() in local.inc to make it work.

What you actually do in that function is completely irrelevant to Auth itself. It only exspects that you either return false, if the user-supplied authentication data was invalid, or a user id, if the user could be validated. Auth then takes care to create the appropriate entries ($auth->auth["uid"] and $auth->auth["exp"]) in the session record.

I still do not understand! What am I supposed to code?

You write your code into local.inc, after you have removed the classes Example_Auth, Example_Default_Auth and Example_Challenge_Auth from that file (keep a copy around, just for reference).

You code a class called My_Auth and you use that name later in your calls to page_open as an argument to the auth feature, as show at the start of this message. Follow the standard rules for deriving persistent classes in PHPLIB when you create your code, that is, do it like this:

---

class My_Auth extends Auth {
var $classname = "My_Auth";
// we inherit $persistent_slots and do not need to modify it.

// later code is inserted here
}

---

Now configure the lifetime of the authentication, that is, how many minutes in the future shall the current value of $auth->auth["exp"] be? Also, name a database connector class and name the table that you will be using to check usernames and passwords.

---

  // insert this code as indicated above.
  var $lifetime = 15;
  var $database_class = "DB_Example";
  var $database_table = "my_special_user_table";

  // later code is inserted here

---

Okay, now we have a basic implementation of My_Auth that is only lacking the required functions auth_loginform() and auth_validatelogin(). Our implementation of auth_loginform() will have access to all $sess variables by globaling $sess into our context (because these can come in handy) and to all $auth variables (via $this).

---

function auth_loginform() {
  global $sess;
  include("loginform.ihtml");
}

---

The loginform is free to do whatever it damn well pleases to create a form for the user to supply the needed values for authentication. It has access to anything $sess and anything $this related.

The loginform will display some input fields for the user, for example a given name, a surname and a password. When the form is submitted back, auth_validatelogin() is being called. The form values are global variables (or $HTTP_x_VARS[]) and must be imported into $auth->auth_validatelogin(). Then, $auth->auth_validatelogin() is free to do whatever it must do to produce a unique identifier for that user (or return false).

Suppose you created input fields named given_name, surname and password. So go ahead, global $given_name, $surname and $password and set $uid to false. Then create the SQL needed to access you user table and retrieve the user record from your database as indicated by $given_name and $surname and $password.

The query may succeed, if a record with matching $given_name, $surname and $password is present. In that case return the uid, which uniquely identifies exactly that (given_name, surname) pair. Else return false.

In code:

---

function auth_validatelogin() {
  // import authentication data
  global $given_name, $surname, $password;

  $uid = false;

  $query = sprintf("select uid
                      from %s
                     where given_name = '%s'
                       and surname = '%s'
                       and password = '%s'",
             $this->database_table,
             $given_name, $surname, $password);
  // we really should use addslashes() here,
  // or have magic_quotes active.

  // $auth->db is our DB_Example database connection
  $this->db->query($query);

  // now check for any results
  while($this->db->next_record()) {
    $uid = $this->db->f("uid");
  }

  // either $uid is false now (no results)
  // or set to the last retrieved value from the uid
  // column.

  // Anyway we are set now and can return control
  return $uid;
}

---

Okay, that's all and useable now. There is room for some improvements, though: First we did not retrieve permission data, so this will not work, if we want to use the perm feature as well.

This is easily changed: Modify the query to select uid, perms instead of select uid alone. Of course, you may call your perm column whatever you like, just adapt the SQL accordingly. Also, add a line after the $uid assignment so that the code looks like this:

---

  $uid = $this->db->f("uid");
  $this->auth["perm"] = $this->db->f("perms");

---

This will store the retrived perms value under the key perm within the $auth->auth[] array. It will be kept around in that place in case $perm is called and starts looking for the current permissions of that user.

Another possible improvement becomes apparent when you try to login and fail to do so correctly: auth_validatelogin() returns false and you hit the loginform again. Empty loginform that is, because we did not remember what you typed into the given_name and surname fields before. If we remembered what you typed, we could easily supply these values back to you so that you can correct them. We would also be able to detect if this is a second, third, ... attempt to login and display an appropriate error message somewhere in that loginform to inform the user of his or her typo. A convenient place to store these values is the $auth->auth array, which is persistent anyway.

Standard Example_Auth uses the field $auth->auth["uname"] to store that value, but you may use any field and as many fields as you like as long as you make sure not to clash with any of the three officially used fields, uid, exp, and perm.

Do not try to turn the global variables $given_name and $surname into persistent variables by calling $sess->register("given_name") and $sess->register("surname")! Remember: These are form variables! Never ever make form variables persistent and never ever trust unvalidated user supplied from the Internet!

So add the folling code just below the "global" line:

---

  $this->auth["gname"] = $given_name;
  $this->auth["sname"] = $surname;

---

and check for these two variables in loginform.ihtml at the appropriate places.

Ok, I did that and it works. I even understood it. Now, what exactly is that uid used for?

It is simply a token to indicate that the user is authenticated. We use a different token for each user, so that we can decide which user we are currently dealing with. You can think of the uid as a primary key for your auth_user table (or whatever it is being called in your current application). The ( given_name, surname ) tuple would also be a possible primary key, albeit a compound one. It is the external, human-readable (and probably sometimes very long) representation of the internal uid. The password field is functionally dependent on either of both key candidates.

The internal user id should never be presented to the user; the ( given_name, surname ) pair is much more natural to handle for the user and easier to remember (A user who does not remember his or her name would probably not be in a state of mind to operate the rest of the application anyway :-).

The internal user id should always be used to identify a user internally within an application, though. That is, because the uid is of a fixed length and has a known form and structure, so you can make assumptions. A given_name or surname may be of any length and may contain about any character, so you probably do not want to use this as a user-reference internally.

But is the uid used internally by PHPLIB?

Yes, if you make use of the user feature of page_open(), that is, if you create user variables.

The User class is actually a subclass of Session. That is, user variables are just like session variables. They are even stored in active_sessions. The only difference is that the session has a different name (it is called Example_User instead of Example_Session, if you use the classes and names supplied in local.inc).

And in Example_User, the user id of the authenticated user becomes the session id in the active_sessions table. That is the reason why we recommend md5(uniqid("abracadabra")) style uids.

3.10 Perm

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.

Instance variables

Instance methods

Accessible instance methods

check($required)

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.

have_perm($required)

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.

perm_sel($name, $current = "", $class = "")

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.

Internal instance methods

permsum($rights)

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.

perm_invalid($does_have, $must_have)

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.

Example

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;
 ?>

---

How permissions work

Your subclass of Perm defines an array $permissions, which translates permission names into bit patterns. For example, the definition of Example_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 Example_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 Example_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.

3.11 User

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.

Instance variables

Instance methods

Accessible instance methods

register($varname)

Works as expected.

unregister($varname)

Works as expected.

delete()

Works as expected.

url($url)

Not useful with User.

purl($url)

Not useful with User.

self_url()

Not useful with User.

pself_url()

Not useful with User.

reimport_get_vars()

Works as expected.

reimport_post_vars()

Works as expected.

reimport_cookie_vars()

Works as expected.

Internal instance methods

get_id()

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.

put_id()

Empty. Not useful with User.

serialize($prefix, &$str)

Works as expected.

freeze()

Works as expected.

thaw()

Works as expected.

gc()

Works as expected. You do not want to use it, though.

reimport_any_vars($arrayname)

Works as expected.

start()

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.

Example

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
  
  var $that_class = "CT_Sql";
}

---

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.