cvs: peardoc /en/package/authentication liveuser.xml

lsmith Thu Aug 11 05:38:56 2005 EDT Modified files: /peardoc/en/package/authentication liveuser.xml Log: - first version of a getting started guide (this is probably broken .. help appreciated)

http://cvs.php.net/diff.php/peardoc/en/package/authentication/liveuser.xml?r1=1.6&r2=1.7&ty=u Index: peardoc/en/package/authentication/liveuser.xml diff -u peardoc/en/package/authentication/liveuser.xml:1.6 peardoc/en/package/authentication/liveuser.xml:1.7 --- peardoc/en/package/authentication/liveuser.xml:1.6 Wed Dec 29 15:40:08 2004 +++ peardoc/en/package/authentication/liveuser.xml Thu Aug 11 05:38:54 2005 @@ -1,15 +1,95 @@ -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <sect1 id="package.authentication.liveuser"> <title>LiveUser</title> <refentry id="package.authentication.liveuser.liveuser-summary"> <refnamediv> <refname>LiveUser</refname> - <refpurpose>External documentation.</refpurpose> + <refpurpose>Getting started guide.</refpurpose> </refnamediv> <refsect1> - <title>LiveUser</title> - <para>There is currently no documentation in the PEAR manual. - Please go to http://pear.limbourg.com</para> + <title>LiveUser and LiveUser_Admin</title> + <para>LiveUser is an advanced authentication and permission framework that comes with a large array of out of the box features which can be used optinally. LiveUser is split in two packages. The base package is called LiveUser and is often refered 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. The other is the LiveUser_Admin package which provides various ways to manage all relevant data, like users, groups/roles, rights and their relations. + +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, PEAR::XML_Tree and PEAR::Auth. + +LiveUser_Admin provides the following key features +You'll be able to add/edit/delete/get things like: +* Rights +* Users +* Groups +* Areas +* Applications +* Subgroups +* ImpliedRights + +And all other entities within LiveUser. + +At the moment we support the following storage containers: +* DB +* MDB +* MDB2 + +Aside from the normal ressources provided in PEAR you can contact the dedicated LiveUser mailinglist: +liveuser@lists.21st-hq.de +http://mailman.21st-hq.de/mailman/listinfo/liveuser + +There is also an exernal wiki dedicated to LiveUser: +http://pear.limbourg.com + +At this point LiveUser is still in beta stage. Even so LiveUser is already being used on a wide range of production websites. A non exaustive list can be found here: +http://pear.limbourg.com/42.html + +The current roadmap for LiveUser can be viewed here: +http://pear.limbourg.com/15.html + +The current roadmap for LiveUser_Admin can be viewed here: +http://pear.limbourg.com/27.html + +A detailed introduction to the core concepts of LiveUser can be found in the following phpmag article: +http://php-mag.net/itr/online_artikel/psecom,id,595,nodeid,114.html + +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. Furthermore the article also does not mention the SQL generator used in the LiveUser_Admin package. This feature has made the API much more flexible since now the entire storage schema is configurable and extensible. It also means that more or less any sort of filtering can be applied with on demand joining. On overview of this API can be found here: +http://pear.limbourg.com/43.html + +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. 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. + +In order to get started with LiveUser the following two articles should help in getting off the ground: +http://jystewart.net/process/archives/2005/07/configuring-liveuser +http://jystewart.net/process/archives/2005/08/getting-started-with-liveuser-permissions/ + +The observer support in LiveUser allows users to automatically have LiveUser call certain callbacks on a number of internal events. It is documented here: +http://pear.limbourg.com/34.html + +Both packages 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 +- example4 illustrates using single authentication sources (database) with permissions (database) in a more real world news administration scenario + +LiveUser_Admin package: +- example 1 illustrates various API calls to most methods in the admin API and custom fields +- example3 illustrates using single authentication sources (database) with permissions (database) and the optional remember me feature in a more real world restricted page access scenario</para> </refsect1> </refentry> </sect1>