[commits] [Wiki] changed: HordeGroupAPI

[Ben Klang]

bklang  Sat, 29 Jan 2011 20:14:35 -0500

Modified page: http://wiki.horde.org/HordeGroupAPI
New Revision:  1.9
Change log:  New proposed group structure (work in progress)

@@ -9,99 +9,74 @@
  ++ Abstract

  In its simplest terms a group consists of an ID and a Name.  The ID  
is unique to that group and is unchanging.  The name is a  
human-friendly name that can be changed as desired.  The source and/or  
format of the group ID should not be of concern to the application  
using it, and should always be obtained/modified/stored through the  
group API calls.  The group ID is the **only** acceptable method as to  
refer to a group, as it is guaranteed to be unique (uniqueness being  
the job of the driver).  The group name is strictly for interface use.

-A group can also have a parent and multiple children.  All references  
to parents and children are to be made through API calls.  Again, it  
is of no concern to the application //how// these relationships are  
maintained, but only that they exist and are free to be used.
+++ Functional Changes
+Horde 4 will deviate from Horde 3 in these key ways:

-For Horde4, we will move away from the object-oriented method of  
managing groups in favor of a Horde_Groups class which will act as a  
group manager.  This should alleviate some of the confusion between  
the different drivers, and eliminate some of the OO overhead.
-
-Also for Horde4, the way we handle saving groups to the backend will  
change.  Instead of keeping track of the changes and committing them  
to storage when updateGroup() is called, all changes should be stored  
on the fly.  There is a bit of a performance hit for this, but it  
simplifies the API, and group modifications are rare enough and  
deliberate enough that this should not be an issue.
-
-++ Open Questions
-
-+++ Flatten Group Structure?
-
-Today the Group subsystem allows for nested groups like this:
-
-
-  !ParentA
-   -> Child1
-   -> Child2
-  !ParentB
-   -> Child3
-   -> Child4
-
-This structure can be seen in Horde's administration screens.
-
-However what is not clear is how those groups relate.  This brings up  
difficult-to-answer questions like:
-* Is a member of the group Child1 automatically a member of ParentA?
-* If permissions are granted to ParentA, do they automatically apply  
to Child1 and Child2?
-
-If you answer "yes" to both questions above then an Administrator  
does not have a convenient way to view all of the group memberships or  
security settings in effect for a given user.  It also complicates  
things like sending notification messages to a group (like in the  
ticketing system or the wiki) because there is no immediate way to  
view all of the users in the group.  The more recursion we allow, the  
more abstract this becomes and the harder to manage.
+* The groups collection will be flat.  Groups cannot be created as  
children of existing groups.

+* Groups can belong to other groups.  In this way complex collections  
of users can be expressed without duplication.
  ----

  ++ Standards

  In order to help keep concepts straight, the following standards  
should be used

  * **$gid** -- Group ID
  * **$group** -- Group Object
+* **$grp_drv** -- Group backend driver
  * **$name** -- Group Name
  * **$parent** -- ID of Group's Parent

  ----

-++ Group:: (Horde_Groups:: for Horde4)
+++ Horde_Group_Backend
+This is the class that does the work of reading from/saving to the  
group storage backend.

-+++ addGroup(@@--- $group +++ $name, $parent@@)
++++ create($name)

-Adds a group to the groups system. @@--- The group must first be created with
-Group::newGroup(), and have any initial users added to it, before this
-function is called. @@
+Creates a new group and returns a new Horde_Group object.

  * Add handlers for $name and $parent parameters from newGroup()

-+++ renameGroup(@@--- $group +++ $gid@@, $newName)
++++ renameGroup($gid, $newName)

-Changes the name of a group without changing its contents or where it
-is in the groups hierarchy.
+Changes the name of a group without affecting its membership list

-+++ removeGroup(@@--- $group +++ $gid@@ @@---, $force = false@@)
++++ removeGroup($gid)

  Removes a group from the groups system permanently.

-+++ getGroupName($gid)
++++ getByName($name)

-Retrieves the name of a group.
+Returns a Horde_Group object based on $name

-+++ getGUID(@@--- $group +++ $gid@@)
+If the name does not match exactly 1 group (too few or too many) it  
will raise Horde_Group_Exception with an appropriate error message

-Returns a globally unique ID for a group.
++++ getById($gid)

-+++ exists(@@--- $group +++ $gid@@)
+Returns Horde_Group object based on the $gid.

-Check if a group exists in the system.
++++ exists($gid)

-+++ getGroupParent($gid@@+++, $deep = false@@)
+Boolean: Check if a group exists in the system.

-Returns the single parent ID @@+++ or a list of parent IDs@@ of the  
given group.
++++ listGroups()

-* Add support to take over getGroupParentList()
+Returns an array of all groups, in the format gid => name.

-+++ listGroups($refresh = false)
++++ listUsers($gid, $recurse = false)

-Returns a list of all groups, in the format gid => name.
+Get a list of every user that is a part of this group ONLY.

-+++ listUsers($gid@@+++, @all = false@@)
-
-Get a list of every user that is a part of this group ONLY.
+If $recurse is true then also check member groups' user list.

  * Add support to take over listAllUsers()

  +++ getGroupMembership($user, $parentGroups = false)

-Get a list of every group that $user is in.
+Returns an array of Horde_Group objects representing the user's membership

  +++ userIsInGroup($user, $gid, $subgroups = true)

  Say if a user is a member of a group or not.