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.
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.
In order to help keep concepts straight, the following standards should be used
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.
Changes the name of a group without changing its contents or where it
is in the groups hierarchy.
Removes a group from the groups system permanently.
Retrieves the name of a group.
Returns a globally unique ID for a group.
Check if a group exists in the system.
Returns the single parent ID or a list of parent IDs of the given group.
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.
Get a list of every group that $user is in.
Say if a user is a member of a group or not.
Add a user to a group.
Remove a user from a group.
deprecated? -- should we always update the backend?
deprecated -- is this used?
new function -- do we need this?
new function -- do we need this?
deprecated in favor of using addGroup()
deprecated -- no longer using group objects.
deprecated -- no longer using group objects.
deprecated -- no need for short names...they're just confusing (K.I.S.S)
deprecated -- no longer using group objects.
deprecated in favor of always using flat lists.
deprecated in favor of getGroupParent()
deprecated in favor of listUsers()
All DatatreeObject_Group functionality has been moved to Group (Horde_Groups) to eliminate OO overhead.