Diff for HordeGroupAPI between 12 and 13

[[toc]]

+ Horde Group API

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.

++ Functional Changes
Horde 4 will deviate from Horde 3 in these key ways:

* 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

----

++ Horde_Group_Backend
This is the class that does the work of reading from/saving to the group storage backend.
This class should not be used directly, instead Horde_Group objects are created and used.

+++ create($name)

Creates a new group and returns a new Horde_Group object.

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

+++ renameGroup($gid, $newName)

Changes the name of a group without affecting its membership list
Should probably be private.  This method exists for the instantiated Horde_Group objects to perform backend operations.  Application code should work with Horde_Group objects.

+++ removeGroup($gid)

Removes a group from the groups system permanently.
Should probably be private.  This method exists for the instantiated Horde_Group objects to perform backend operations.  Application code should work with Horde_Group objects.

+++ getByName($name)

Returns a Horde_Group object based on $name

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

+++ getById($gid)

Returns Horde_Group object based on the $gid.

+++ exists($gid)

Boolean: Check if a group exists in the system.

+++ listGroups()

Returns an array of all groups, in the format gid => name.

+++ listUsers($gid, $recurse = 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)

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.

+++ addUser($gid, $username)

Add a user to a group.

* Should be able to handle arrays for both parameters.
Should probably be private.  This method exists for the instantiated Horde_Group objects to perform backend operations.  Application code should work with Horde_Group objects.

+++ removeUse($gid,removeUser($gid, $username)

Remove a user from a group.
Should probably be private.  This method exists for the instantiated Horde_Group objects to perform backend operations.  Application code should work with Horde_Group objects.

*
* Should be able to handle arrays for both parameters.


++ Horde_Group

This object represents a group

+++ new($name, $create = true)
Returns an instance of a Horde group.  If $create is true and the group does not exist, it is created.  If $create is false and the group does exist, or if $create is true and the group already exists, a Horde_Group_Exception is raised.

+++ id()

+++ addUser($username)

+++ removeUser($username)

+++ listUsers($recurse = true)

+++ delete()

+++ rename()