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

moosh Sun Sep 11 14:48:08 2005 EDT Modified files: /peardoc/en/package/authentication liveuser.xml Log: - warp line 80 - indent 1 - add blank line (for translator facility)

http://cvs.php.net/diff.php/peardoc/en/package/authentication/liveuser.xml?r1=1.14&r2=1.15&ty=u Index: peardoc/en/package/authentication/liveuser.xml diff -u peardoc/en/package/authentication/liveuser.xml:1.14 peardoc/en/package/authentication/liveuser.xml:1.15 --- peardoc/en/package/authentication/liveuser.xml:1.14 Sun Sep 11 14:32:07 2005 +++ peardoc/en/package/authentication/liveuser.xml Sun Sep 11 14:48:05 2005 @@ -1,228 +1,327 @@ -<!-- $Revision: 1.14 $ --> +<!-- $Revision: 1.15 $ --> <sect1 id="package.authentication.liveuser"> -<title>LiveUser</title> -<refentry id="package.authentication.liveuser.liveuser-summary"> - <refnamediv> - <refname>LiveUser</refname> - <refpurpose>Getting started guide.</refpurpose> - </refnamediv> -<refsect1> - <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. - </para> - - <para>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. - </para> - - <para> - 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 + <title>LiveUser</title> + <refentry id="package.authentication.liveuser.liveuser-summary"> + <refnamediv> + <refname>LiveUser</refname> + <refpurpose>Getting started guide.</refpurpose> + </refnamediv> + <refsect1> + <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. + </para> + + <para> + 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. + </para> + + <para> + 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. - </para> + </para> - <para> - 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! - </para> + <para> + 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! + </para> - <para> + <para> Currently available are containers using: PEAR::DB, PEAR::MDB, PEAR::MDB2, PEAR::XML_Tree and PEAR::Auth. - </para> + </para> - <para> + <para> LiveUser_Admin provides the following key features You'll be able to add/edit/delete/get things like: <itemizedlist> - <listitem> - <simpara>Rights</simpara> - </listitem> - <listitem> - <simpara>Users</simpara> - </listitem> - <listitem> - <simpara>Groups</simpara> - </listitem> - <listitem> - <simpara>Areas</simpara> - </listitem> - <listitem> - <simpara>Applications</simpara> - </listitem> - <listitem> - <simpara>Subgroups</simpara> - </listitem> - <listitem> - <simpara>ImpliedRights</simpara> - </listitem> + <listitem> + <simpara>Rights</simpara> + </listitem> + <listitem> + <simpara>Users</simpara> + </listitem> + <listitem> + <simpara>Groups</simpara> + </listitem> + <listitem> + <simpara>Areas</simpara> + </listitem> + <listitem> + <simpara>Applications</simpara> + </listitem> + <listitem> + <simpara>Subgroups</simpara> + </listitem> + <listitem> + <simpara>ImpliedRights</simpara> + </listitem> </itemizedlist> - </para> + </para> - <para> + <para> And all other entities within LiveUser. At the moment we support the following storage containers: <itemizedlist> <listitem> - <simpara>DB</simpara> - </listitem> + <simpara>DB</simpara> + </listitem> <listitem> - <simpara>MDB</simpara> - </listitem> + <simpara>MDB</simpara> + </listitem> <listitem> - <simpara>MDB2</simpara> - </listitem> + <simpara>MDB2</simpara> + </listitem> </itemizedlist> - </para> + </para> - <para> - Aside from the normal ressources provided in PEAR you can contact the dedicated LiveUser mailinglist: + <para> + Aside from the normal ressources provided in PEAR you can contact the + dedicated LiveUser mailinglist: + <ulink url="mailto:&url.liveuser.mailinglist.email;">&url.liveuser.mailinglist.email;</ulink> <ulink url="&url.liveuser.mailinglist.url;">&url.liveuser.mailinglist.url;</ulink> - </para> + </para> - <para> + <para> There is also an external wiki dedicated to LiveUser: <ulink url="&url.liveuser.wiki;">&url.liveuser.wiki;</ulink> - </para> - - <para> - At this point LiveUser is still in beta stage. Even so LiveUser is already - being used on a wide range of production websites. + </para> + + <para> + 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: <ulink url="&url.liveuser.wiki.references;">&url.liveuser.wiki.references;</ulink> - </para> - - <para> + </para> + + <para> The current roadmap for LiveUser can be viewed here: + <ulink url="&url.liveuser.wiki.roadmap.client;">&url.liveuser.wiki.roadmap.client;</ulink> - </para> - - <para> + </para> + + <para> The current roadmap for LiveUser_Admin can be viewed here: + <ulink url="&url.liveuser.wiki.roadmap.admin;">&url.liveuser.wiki.roadmap.admin;</ulink> - </para> - - <para> - A detailed introduction to the core concepts of LiveUser can be found in the following phpmag article: + </para> + + <para> + A detailed introduction to the core concepts of LiveUser can be found + in the following phpmag article: <ulink url="&url.liveuser.phpmag.article1;">&url.liveuser.phpmag.article1;</ulink> - </para> - - <para> - 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. + </para> + + <para> + 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. + 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: <ulink url="&url.liveuser.wiki.admin.api;">&url.liveuser.wiki.admin.api;</ulink> - </para> - - <para> - 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 its a two step process for both - the auth and perm: (1) generate the schema xml file, (2) install the schema. - </para> - <para> - 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 + </para> + + <para> + 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 its a two step process for both the auth and perm: (1) + generate the schema xml file, (2) install the schema. + </para> + + <para> + 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. - </para> - - <para> + </para> + + <para> An ER diagram of the database structure can be found here: <ulink url="&url.liveuser.backendmedia.dbschema;">&url.liveuser.backendmedia.dbschema;</ulink> - </para> - - <para> - The diagram details what tables are needed for what permission complexity level. - If you want to prevent the installer from installing tables you dont need you can - modify the "tables" property of the instance of the permission container you pass to - the generateSchema() method in the installer. - </para> - - <para> - In order to get started with LiveUser the following two articles should help in getting off the ground: + </para> + + <para> + The diagram details what tables are needed + for what permission complexity level. + + If you want to prevent the installer from installing tables you dont need + you can modify the "tables" property of the instance of the permission + container you pass to the generateSchema() method in the installer. + </para> + + <para> + In order to get started with LiveUser the following two articles should + help in getting off the ground: + <ulink url="&url.liveuser.jystewart.config;">&url.liveuser.jystewart.config;</ulink> <ulink url="&url.liveuser.jystewart.start;">&url.liveuser.jystewart.start;</ulink> - </para> + </para> - <para> - The observer support in LiveUser allows users to automatically have LiveUser call certain - callbacks on a number of internal events. It is documented here: + <para> + The observer support in LiveUser allows users to automatically have LiveUser + call certain callbacks on a number of internal events. + + It is documented here: <ulink url="&url.liveuser.wiki.observer;">&url.liveuser.wiki.observer;</ulink> - </para> - - <para> - 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. - </para> - - <para> + </para> + + <para> + 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. + </para> + + <para> LiveUser package: <itemizedlist> - <listitem><simpara>example1 illustrates using only a single authentication source (in this case XML) - with several aliased fields and a custom field.</simpara></listitem> - <listitem><simpara>example2 illustrates using a single authentication with - permissions (in this case XML) with the optional remember me feature and several aliased fields</simpara></listitem> - <listitem><simpara>example4 illustrates using multiple authentication sources - (XML and database) with permissions (database) in a more real world news administration scenario</simpara></listitem> - <listitem><simpara>example4 illustrates using single authentication sources - (database) with permissions (database) in a more real world news administration scenario</simpara></listitem> + <listitem> + <simpara> + example1 illustrates using only a single authentication source + (in this case XML) + with several aliased fields and a custom field. + </simpara> + </listitem> + <listitem> + <simpara> + example2 illustrates using a single authentication with permissions + (in this case XML) + with the optional remember me feature and several aliased fields + </simpara> + </listitem> + <listitem> + <simpara> + example4 illustrates using multiple authentication sources + (XML and database) with permissions (database) in a more real world news + administration scenario + </simpara> + </listitem> + <listitem> + <simpara> + example4 illustrates using single authentication sources (database) with + permissions (database) in a more real world news administration scenario + </simpara> + </listitem> </itemizedlist> LiveUser_Admin package: <itemizedlist> - <listitem><simpara>example 1 illustrates various API calls to - most methods in the admin API and custom fields</simpara></listitem> - <listitem><simpara>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</simpara></listitem> + <listitem> + <simpara> + example 1 illustrates various API calls to most methods in the admin API + and custom fields + </simpara> + </listitem> + <listitem> + <simpara> + 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 + </simpara> + </listitem> </itemizedlist> - </para> -</refsect1> -</refentry> + </para> + </refsect1> + </refentry> </sect1> <!-- Generated by phpDocumentor v 1.2.2 http://www.phpdoc.org --> <!-- Keep this comment at the end of the file