MySQL auth module documentation

This patch completes the documentation of the MySQL SQL statements
that are necessary to run the mysql OO auth module in mysql.conf.php.example.

Some pattern names in the code were not in line - fixed.

darcs-hash:20051107210740-4145d-cdf140b6d14664ce9c1a85f67e1bf8feb294c17b.gz

1 files changed, 84 insertions, 5 deletions

diff --git a/conf/mysql.conf.php.example b/conf/mysql.conf.php.example
index 1c70e794e..ffe35c466 100644
--- a/conf/mysql.conf.php.example
+++ b/conf/mysql.conf.php.example
@@ -66,41 +66,120 @@ $conf['auth']['mysql']['checkPass']   = "SELECT pass
                                          WHERE login='%u'
                                          AND name='%g'";
 
+/* This statement is used to get all groups a user is member of. The result should
+ * be a table containing all groups the given user is member of. The module access
+ * the group name as 'group' so a alias might be nessecary.
+ * following patters will be replaced:
+ *   %u    user name
+ */
 $conf['auth']['mysql']['getGroups']   = "SELECT name as `group`
                                          FROM groups g, users u, usergroup ug
                                          WHERE u.uid = ug.uid
                                          AND g.gid = ug.gid
                                          AND u.login='%u'";
+
+/* This statement should return a table with exact one row containing information
+ * about one user. The field needed are:
+ * 'pass'  containing the encrypted or clear text password
+ * 'name'  the user's full name
+ * 'mail'  the user's email address
+ * Keep in mind that Dokuwiki will access thise information through the names
+ * listed above so aliasses might be neseccary.
+ * following patters will be replaced:
+ *   %u    user name
+ */
 $conf['auth']['mysql']['getUserInfo'] = "SELECT pass, CONCAT(firstname,' ',lastname) AS name, email AS mail
                                          FROM users
                                          WHERE login='%u'";
+
+/* This statement should return a table containing all user login names that meet 
+ * certain filter criteria. The filter expressions will be added case dependend by
+ * the module. At the end a sort expression will be added.
+ * Important is that this list contains no double entries fo a user. Each user
+ * name is only allowed once in the table.
+ * The login name will be accessed as 'user' to a alias might be neseccary.
+ * No patterns will be replaced in this statement but following patters will be
+ * replaced in the filter expressions:
+ *   %u  in FilterLogin  user's login name
+ *   %n  in FilterName   user's full name
+ *   %e  in FilterEmail  user's email address
+ *   %g  in FilterGroup  group name
+ */
 $conf['auth']['mysql']['getUsers']    = "SELECT DISTINCT login AS user
                                          FROM users AS u 
                                          LEFT JOIN usergroup AS ug ON u.uid=ug.uid
                                          LEFT JOIN groups AS g ON ug.gid=g.gid";
-
+$conf['auth']['mysql']['FilterLogin'] = "login LIKE '%u'";
+$conf['auth']['mysql']['FilterName']  = "CONCAT(firstname,' ',lastname) LIKE '%n'";
+$conf['auth']['mysql']['FilterEmail'] = "email LIKE '%e'";
+$conf['auth']['mysql']['FilterGroup'] = "name LIKE '%g'";
 $conf['auth']['mysql']['SortOrder']   = "ORDER BY login";
-$conf['auth']['mysql']['FilterLogin'] = "login LIKE '%s'";
-$conf['auth']['mysql']['FilterName']  = "CONCAT(firstname,' ',lastname) LIKE '%s'";
-$conf['auth']['mysql']['FilterEmail'] = "email LIKE '%s'";
-$conf['auth']['mysql']['FilterGroup'] = "name LIKE '%s'";
 
+/* This statement should add a user to the database. Minimum information to 
+ * store are: login name, password, email address and full name.
+ * Following patterns will be replaced:
+ *   %u  user's login name
+ *   %p  password (encrypted or clear text, depends on 'encryptPass')
+ *   %e  email address
+ *   %n  user's full name
+ */ 
 $conf['auth']['mysql']['addUser']     = "INSERT INTO users
                                          (login, pass, email, firstname, lastname)
                                          VALUES ('%u', '%p', '%e',
                                          SUBSTRING_INDEX('%n',' ', 1),
                                          SUBSTRING_INDEX('%n',' ', -1))";
+
+/* This statement should remove a user fom the database.
+ * Following patterns will be replaced:
+ *   %u    user's login name
+ *   %uid  id of a user dataset
+ */
 $conf['auth']['mysql']['delUser']     = "DELETE FROM users
                                          WHERE uid='%uid'";
+
+/* This statement should add a group to the database.
+ * Following patterns will be replaced:
+ *   %g    group name
+ */
 $conf['auth']['mysql']['addGroup']    = "INSERT INTO groups (name)
                                          VALUES ('%g')";
+
+/* This statement should remove a group fom the database.
+ * Following patterns will be replaced:
+ *   %g    group name
+ *   %gid  id of a group dataset
+ */
 $conf['auth']['mysql']['delGroup']    = "DELETE FROM groups
                                          WHERE gid='%gid'";
+
+/* This statement should connect a user to a group (a user become member
+ * of that group).
+ * Following patterns will be replaced:
+ *   %u    user's login name
+ *   %uid  id of a user dataset
+ *   %g    group name
+ *   %gid  id of a group dataset
+ */
 $conf['auth']['mysql']['addUserGroup']= "INSERT INTO usergroup (uid, gid)
                                          VALUES ('%uid', '%gid')";
+
+/* This statement should remove a single connection from a user to a
+ * group (a user quits membership of that group).
+ * Following patterns will be replaced:
+ *   %u    user's login name
+ *   %uid  id of a user dataset
+ *   %g    group name
+ *   %gid  id of a group dataset
+ */
 $conf['auth']['mysql']['delUserGroup']= "DELETE FROM usergroup
                                          WHERE uid='%uid'
                                          AND gid='%gid'";
+
+/* This statement should remove all connections from a user to any group
+ * (a user quits membership of all groups).
+ * Following patterns will be replaced:
+ *   %uid  id of a user dataset
+ */
 $conf['auth']['mysql']['delUserRefs'] = "DELETE FROM usergroup
                                          WHERE uid='%uid'";
 ?>