The "Horde_Kolab_Server" package allows you to access the Kolab
Server user database.


Installation of the package
===========================

The package is being distributed as a standard PEAR package by the
Horde project. As long as you have PEAR installed, installation should
be straight forward.

 pear channel-discover pear.horde.org
 pear install --force channel://pear.horde.org/Horde_Kolab_Server

"pear" will probably complain about the library (and its dependencies)
not being marked stable yet but the "--force" option allows to ignore
these warnings.


Using the package
===========================

This section will present some examples on how to fetch information
from the Kolab Server database.

Currently the package only provides a LDAP and a test driver as
possible backends. The test driver is for internal testing purposes
only and emulates a LDAP system without requiring access to a real
LDAP database. So most developers will use the LDAP back end. In order
to enable the driver some basic configuration is required.

Configurations for Horde are always set in the global "$conf"
variable. A possible configuration for "Horde_Kolab_Server" could look
like this:

 global $conf;
 $conf['kolab']['server']['driver'] = 'ldap';
 $conf['kolab']['server']['params']['server'] = 'example.com';
 $conf['kolab']['server']['params']['base_dn'] = 'dc=example,dc=com';
 $conf['kolab']['server']['params']['bind_dn'] = 'cn=nobody,cn=internal,dc=example,dc=com';
 $conf['kolab']['server']['params']['bind_pw'] = 'MY_VERY_SECRET_PASSWORD';

With this base configuration the developer can load the code and
initialize the server object:

 require_once 'Horde/Kolab/Server.php';
 $server = Horde_Kolab_Server::singleton();

This server handler serves two primary purposes:

 * Identifying the ID of an object on basis of a given attribute
 * Fetching an object from the database based on the ID

A common request to the Kolab LDAP database is to return the ID of a
user given a mail address. The "$server" object will return the "DN"
("distinguished name") of the object in the LDAP database:

 $dn = $server->dnForMailAddress('wrobel@example.com');

The returned "DN" could look like this:

 var_dump($dn);

 string(32) "cn=Gunnar Wrobel,dc=example,dc=com"

For alternative methods of retrieving a particular "DN" you should
consult the detailed package documentation (see below).

This "DN" can now be used to fetch the object from the database:

 $object = $server->fetch($dn);

The "$server" object will always return an object of class
"Horde_Kolab_Server_Object". But you will receive a sub class of this
parent class that matches the type of the object. For the example
given above the server handler returns an object of type
"Horde_Kolab_Server_Object_user":

 var_dump(get_class($object));

 string(30) "Horde_Kolab_Server_Object_user"

Depending on the sub class such an object presents different
features. One primary method is common to all the objects though:
Fetching attribute values with "get()".

 $attr = $object->get(Horde_Kolab_Server_Object::ATTRIBUTE_CN);

"Horde_Kolab_Server_Object::ATTRIBUTE_CN" is being used to retrieve
the "common name" of the object:

 var_dump($attr);

 string(13) "Gunnar Wrobel"

For additional details about the different objects and attribute types
you should consult the detailed package documentation (see below).


Detailed package documentation
==============================

A detailed documentation based on the code comments and extracted via
phpDocumentor can be found at
http://dev.horde.org/api/framework/. Simply select the package
"Kolab_Server" in the package selection box in the upper right
corner.


ToDo
====

Currently the package only implements read access. At some point it should allow write access, too. This is required to convert the Kolab webadmin to use this package.