[[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.
---
++ 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. In particular {{getParent()}}, {{getChildren()}}, and {{getParentList()}}. 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.
++ Standards
In order to help keep concepts straight, the following standards should be used
* **$gid** -- Group ID
* **$group** -- Group Object
* **$name** -- Group Name
++ Classes
+++ Group
++++ newGroup($name, $parent = DATATREE_ROOT)
++++ getGroup($gid)
++++ getGroupById($gid)
##red|deprecated## -- in favor of using addGroup()
++++ getGUID($group)
++++ getGroup($gid)
++++ addGroup($group)
++++ updateGroup($group)
++++ renameGroup($group, $newName)
++++ removeGroup($group, $force = false)
++++ getGroupName($gid)
++++ getGroupShortName($group)
++++ getGroupId($group)
++++ exists($gid)
++++ getGroupParents($gid)
++++ getGroupParent($gid)
++++ getGroupParentList($gid)
++++ listGroups($refresh = false)
++++ listUsers($gid)
++++ listAllUsers($gid)
++++ getGroupMembership($user, $parentGroups = false)
++++ userIsInGroup($user, $gid, $subgroups = true)
++++##red|deprecated## -- no longer using group objects.
++++ getGroupById($gid)
##red|deprecated## -- no longer using group objects.
++++ getGUID($group)
++++ addGroup($group)
Add handlers for $name and $parent parameters from newGroup()
++++ updateGroup($group)
##yellow|deprecated?## -- should we always update the backend?
++++ renameGroup($group, $newName)
++++ removeGroup($group, $force = false)
++++ getGroupName($gid)
++++ getGroupShortName($group)
##red|deprecated## -- no need for short names...they're just confusing.
++++ getGroupId($group)
##red|deprecated## -- no longer using group objects.
++++ exists($gid)
++++ getGroupParents($gid)
##red|deprecated## -- in favor of always using flat lists.
++++ getGroupParent($gid)
Add support to take over getGroupParentList()
++++ getGroupParentList($gid)
##red|deprecated## -- in favor of getGroupParent()
++++ listGroups($refresh = false)
++++ listUsers($gid)
Add support to take over listAllUsers()
++++ listAllUsers($gid)
##red|deprecated## -- in favor of listUsers()
++++ getGroupMembership($user, $parentGroups = false)
++++ userIsInGroup($user, $gid, $subgroups = true)
++++ getLevel($gid)
##yellow|deprecated## -- is this used?
++++ addUser($username, $gid)
##green|new function## -- no longer using group objects.
Should be able to handle arrays for both parameters.
++++ removeUser($username, $gid)
##green|new function## -- no longer using group objects.
Should be able to handle arrays for both parameters.
++++ getAuditLog($gid)
##yellow|new function## -- do we need this?
++++ clearAuditLog($gid)
##yellow|new function## -- do we need this?
+++ !DatatreeObject_Group (##red|deprecated##)
+++All !DatatreeObject_Group functionality has been moved to Group (Horde_Groups) to eliminate OO overhead.
++++ setGroupOb(&$groupOb)
++++ getId()
++++ save()
++++ addUser($username, $update = true)
++++ removeUser($username, $update = true)
++++ listUser()
++++ listAllUsers()
++++ getAuditLog()
++++ clearAuditLog()