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