Introduction

Introduction
–
About LiveUser

About LiveUser

LiveUser is an advanced authentication and permission
framework that comes with a large array of out of the box
features which can be used optionally.
In short, the LiveUser package, provides Access Control List (ACL) functionality.
The base class is called LiveUser and is often
referred to as the "client"
and is what will be commonly be used to authenticate a specific user
and then optionally make permission checks on this user.

LiveUser provides the following key features:
The LiveUser class takes care of the login process and can be configured to
use a certain permission container and one or more different
auth containers.
That means, you can have your users' data scattered amongst many data
containers and have the LiveUser class try each defined container until
the user is found.
For example, you can have all website users who can apply for a new account
online on the webserver's local database.
Also, you want to enable all your company's employees to login to the site
without the need to create new accounts for all of them.
To achieve that, a second container can be defined to be used by the
LiveUser class.

You can also define a permission container of your choice that will manage
the rights for each user.
Depending on the container, you can implement any kind of permission schemes
for your application while having one consistent API.

Using different permission and auth containers,
it's easily possible to integrate newly written applications with older ones
that have their own ways of storing permissions and user data.
Just make a new container type and you're ready to go!

Currently available are containers using:
PEAR::DB, PEAR::MDB, PEAR::MDB2, ext/PDO, PEAR::XML_Tree, Session and PEAR::Auth.

A detailed introduction to the core concepts of LiveUser can be found
in the following phpmag
article.

This article was published in april 2004 and is therefore not entirely
uptodate.
However the core principles remain unchanged and most of the recent changes
resolve around making the API more consistent and flexible.
As a result the API examples are mostly out of date.
The article also fails to mention the fact that the permission containers
are now separated in a logic and a storage layer.
This was done to remove logic duplication as well as to allow the
implementation of a stackable storage approach, where users could configure
LiveUser to first call a cache storage layer, which in turn would fetch
the necessary data on demand from the actual storage layer.

A more recent article providing a step by step guide to LiveUser and the
different permission containers can be found
here.

Before you can use LiveUser you will need to setup the necessary data
structures for the chosen container.
Through the use of the configuration options it is possible to customize
alot of the aspects of the storage layer.
Most notably it is possible to alias field and table names.
This should make it possible to integrate any legacy data into LiveUser.
Depending on the container chosen you may have to use the database schema
installer.
The installer requires the MDB2_Schema and MDB2 packages and is able to
handle most configuration options properly to be able to install the
database schema directly into your database.
You can find the install class in "[PEAR]/data/misc/schema/install.php".
There is some sample code which is partially commented out at the top.
Basically it's a two step process for both the auth and perm: (1)
generate the schema xml file, (2) install the schema.

During the installation process the installer will create backup files of
the installed schema.
These files will enable the installer to attempt to alter the database if
run again with a different configuration.
However if these files exist the installer will always attempt to alter
instead of creating the tables from scratch as long as you are using the sam
DSN.
If for some reason you need to create the tables from scratch again then
please delete the backup files with the matching DSN.
You can find the installer inside the data directory of your pear install
directory.
Its called install.php and at the top of the file you will find a number of
sample API calls which are commented out.

The diagram details what tables are needed
for what permission complexity level.
If you want to prevent the installer from installing tables you don't need
you can modify the "tables" property of the instance of the permission
container you pass to the generateSchema() method in the installer.

In order to get started with LiveUser the following
twoarticles should
help in getting off the ground.

The observer support in LiveUser allows users to automatically have LiveUser
call certain callbacks on a number of internal events.
It is documented
here.

LiveUser also ship with a wide range of examples.
These will be installed into the "docs" directory in your PEAR install
directory.
They try to illustrate various usage scenarios.
The database examples come with a schema file please see the demodata.php
in the examples root folder of the LiveUser package for details on how to
install these schema files from the command line or from a browser.
You will once again need MDB2_Schema to be able to install the schema files.

LiveUser package:

example1 illustrates using only a single authentication source
(in this case XML)
with several aliased fields and a custom field.

example2 illustrates using a single authentication with permissions
(in this case XML)
with the optional remember me feature and several aliased fields

example4 illustrates using multiple authentication sources
(XML and database) with permissions (database) in a more real world news
administration scenario

example5 illustrates using single authentication sources (database) with
permissions (database) in a more real world news administration scenario