[cvs] [Wiki] changed: HordeGroupAPI

[Ben Chavet]

ben  Sun, 10 Dec 2006 00:18:00 -0800

Modified page: http://wiki.horde.org/HordeGroupAPI
New Revision:  1.3
Change log:  a bit of reorganization

@@ -1,119 +1,128 @@
  [[toc]]
  
  + Horde Group API
  
-This document is intended to clarify the Horde Group API.  Primarily in order to write a new LDAP driver as discussed by the Bens in IRC, but also to provide a solid target for applications to move toward.
+This document is intended to clarify the Horde Group API, and to provide a solid target for applications to move toward for Horde4.  Motivation for this document was spurred from the conversation between the Bens on IRC regarding the "proper" way to handle groups with LDAP.
  
----
+----
  
  ++ 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.
+
+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.
+
+----
  
  ++ Standards
  
  In order to help keep concepts straight, the following standards should be used
  
  * **$gid** -- Group ID
  * **$group** -- Group Object
  * **$name** -- Group Name
+* **$parent** -- ID of Group's Parent
+
+----
  
-++ Classes
+++ API
  
  +++ Group
  
-++++ newGroup($name, $parent = DATATREE_ROOT)
+++++ addGroup($group|$name, $parent)
  
-##red|deprecated## -- in favor of using addGroup()
+Add handlers for $name and $parent parameters from newGroup()
  
-++++ getGroup($gid)
+++++ renameGroup($group|$gid, $newName)
  
-##red|deprecated## -- no longer using group objects.
+++++ removeGroup($group|$gid, $force = false)
  
-++++ getGroupById($gid)
+++++ getGroupName($gid)
  
-##red|deprecated## -- no longer using group objects.
+++++ getGUID($group|$gid)
  
-++++ getGUID($group)
+++++ exists($group|$gid)
  
-++++ addGroup($group)
+++++ getGroupParent($gid)
  
-Add handlers for $name and $parent parameters from newGroup()
+Add support to take over getGroupParentList()
  
-++++ updateGroup($group)
+++++ listGroups($refresh = false)
  
-##yellow|deprecated?## -- should we always update the backend?
+++++ listUsers($gid)
  
-++++ renameGroup($group, $newName)
+Add support to take over listAllUsers()
  
-++++ removeGroup($group, $force = false)
+++++ getGroupMembership($user, $parentGroups = false)
  
-++++ getGroupName($gid)
+++++ userIsInGroup($user, $gid, $subgroups = true)
  
-++++ getGroupShortName($group)
+++++ @@+++ addUser($username, $gid) @@
  
-##red|deprecated## -- no need for short names...they're just confusing.
+new function -- no longer using group objects.
  
-++++ getGroupId($group)
+Should be able to handle arrays for both parameters.
  
-##red|deprecated## -- no longer using group objects.
+++++ @@+++ removeUser($username, $gid) @@
  
-++++ exists($gid)
+new function -- no longer using group objects.
  
-++++ getGroupParents($gid)
+Should be able to handle arrays for both parameters.
  
-##red|deprecated## -- in favor of always using flat lists.
+++++ updateGroup($group)
  
-++++ getGroupParent($gid)
+##yellow|deprecated?## -- should we always update the backend?
  
-Add support to take over getGroupParentList()
+++++ getLevel($gid)
  
-++++ getGroupParentList($gid)
+##yellow|deprecated## -- is this used?
  
-##red|deprecated## -- in favor of getGroupParent()
+++++ getAuditLog($gid)
  
-++++ listGroups($refresh = false)
+##yellow|new function## -- do we need this?
  
-++++ listUsers($gid)
+++++ clearAuditLog($gid)
  
-Add support to take over listAllUsers()
+##yellow|new function## -- do we need this?
  
-++++ listAllUsers($gid)
  
-##red|deprecated## -- in favor of listUsers()
+++++ @@--- newGroup($name, $parent = DATATREE_ROOT) @@
  
-++++ getGroupMembership($user, $parentGroups = false)
+deprecated in favor of using addGroup()
  
-++++ userIsInGroup($user, $gid, $subgroups = true)
+++++ @@--- getGroup($gid) @@
  
-++++ getLevel($gid)
+deprecated -- no longer using group objects.
  
-##yellow|deprecated## -- is this used?
+++++ @@--- getGroupById($gid) @@
  
-++++ addUser($username, $gid)
+deprecated -- no longer using group objects.
  
-##green|new function## -- no longer using group objects.
+++++ @@--- getGroupShortName($group) @@
  
-Should be able to handle arrays for both parameters.
+deprecated -- no need for short names...they're just confusing (K.I.S.S)
  
-++++ removeUser($username, $gid)
+++++ @@--- getGroupId($group) @@
  
-##green|new function## -- no longer using group objects.
+deprecated -- no longer using group objects.
  
-Should be able to handle arrays for both parameters.
+++++ @@--- getGroupParents($gid) @@
  
-++++ getAuditLog($gid)
+deprecated in favor of always using flat lists.
  
-##yellow|new function## -- do we need this?
+++++ @@--- getGroupParentList($gid) @@
  
-++++ clearAuditLog($gid)
+deprecated in favor of getGroupParent()
+
+++++ @@--- listAllUsers($gid) @@
+
+deprecated in favor of listUsers()
  
-##yellow|new function## -- do we need this?
  
-+++ !DatatreeObject_Group (##red|deprecated##)
++++ @@--- !DatatreeObject_Group @@
  
  All !DatatreeObject_Group functionality has been moved to Group (Horde_Groups) to eliminate OO overhead.
  
  ++++ setGroupOb(&$groupOb)