thekid/rfc — Issue #147: RFC 0147: New LDAP API
Author: thekid
Created: 2011-10-09 15:24:36+00:00
State: open
Labels: draft, rfc

Scope of Change
====
A new LDAP API will be created and will supersede the old classes.

Rationale
====
* Changes to the existing API would create numerous BC breaks.
* Be consistent with other APIs accessing remote systems (FtpConnection,
HttpConnection, SybaseConnection, ...)

Functionality
====

Entry point
----
The class peer.ldap.LdapConnection class will be the entry point class.

```php

*

* version: Specifies the LDAP protocol version to use.
* Defaults to 3
*

*

* autoconnect: Specifies whether to automatically connect on
* first use. Defaults to no
*

*

*
* @param string dsn
*/
public function __construct($dsn) {
// ...
}

/**
* Connect (and login, if necessary)
*
* @throws peer.ConnectException in case of a connection error
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function connect() {
// ...
}

/**
* Disconnect
*
*/
public function close() {
// ...
}

/**
* Search
*
* @param peer.ldap.LdapQuery q
* @return peer.ldap.LdapResults
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function searchFor(LdapQuery $q) {
// ...
}

/**
* List all entries in a given base DN
*
* @param peer.ldap.DN base
* @return peer.ldap.LdapResults
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function entriesIn(DN $base) {
// ...
}

/**
* Retrieve an entry by its DN
*
* @param peer.ldap.DN dn
* @return peer.ldap.LdapEntry entry (empty if it doesn't exist)
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function entryFor(DN $dn) {
// ...
}

/**
* Retrieve an entry by its DN
*
* @param peer.ldap.DN dn
* @return peer.ldap.LdapEntry new entry
* @throws lang.IllegalStateException in case the given entry exists
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function newEntry(DN $dn) {
// ...
}

/**
* Retrieve an entry by its DN
*
* @param peer.ldap.DN dn
* @return peer.ldap.LdapEntry entry or NULL if it doesn't exist
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function findBy(DN $dn) {
// ...
}

/**
* Retrieve an entry by its DN
*
* @param peer.ldap.DN dn
* @return peer.ldap.LdapEntry entry
* @throws lang.ElementNotFoundException in case the given entry cannot be foujnd
* @throws peer.ldap.LdapException in case of a protocol error
*/
public function getBy(DN $dn) {
// ...
}
}
?>
```

Examples
----

Reading an LDAP entry by its Distinguished Name (DN)

```php
getBy(new DN('uid=kurt,ou=People,dc=OpenLDAP,dc=Org'))->toString();
$lc->close();
?>
```

Search for entries:

```php
seachFor(new LdapQuery('ou=People,dc=OpenLDAP,dc=Org', '(objectClass=*)'));
echo $r->toString(), "\n";

// Iterate using foreach
foreach ($r->entries() as $entry) {
echo '- ', $entry->toString(), "\n";
}
$lc->close();
?>
```

List entries inside a given base DN:

```php
entriesIn(new DN('ou=People,dc=OpenLDAP,dc=Org'));
echo $r->toString(), "\n";

// Iterate using foreach
foreach ($r->entries() as $entry) {
echo '- ', $entry->toString(), "\n";
}
$lc->close();
?>
```

Create a new or update an existing entry:

```php
entryFor(new DN('uid=timm,ou=People,dc=Example,dc=Com'))); {
$e->setObjectClass('inetOrgPerson');
$e->setAttribute('displayName', 'Timm Friebe');
$e->setAttribute('mail', 'timm@example.com');
$e->setAttribute('sn', 'Friebe');
// ...

$e->save();
}
$lc->close();
?>
```

Create a new entry:

```php
newEntry(new DN('uid=timm,ou=People,dc=Example,dc=Com'))); {
$e->setObjectClass('inetOrgPerson');
$e->setAttribute('displayName', 'Timm Friebe');
$e->setAttribute('mail', 'timm@example.com');
$e->setAttribute('sn', 'Friebe');
// ...

$e->save();
}
$lc->close();
?>
```

Delete an existing entry:

```php
getBy(new DN('uid=timm,ou=People,dc=Example,dc=Com'))->delete();
$lc->close();
?>
```

Security considerations
====
n/a

Speed impact
====
None.

Dependencies
====
n/a

Related documents
====
- http://php3.de/ldap
PHP Manual: LDAP Functions

Comments
====
n/a