# Zend_Ldap

`Zend_Ldap` is the base interface into a LDAP server. It provides connection and binding methods as well as methods to operate on the LDAP tree.

## Zend_Ldap API

Method | Description
--- | ---
`string filterEscape(string $str)` | Escapes a value to be used in a LDAP filter according to RFC 2254. This method is deprecated, please use `Zend_Ldap_Filter_Abstract::escapeValue()` instead.
`boolean explodeDn($dn, array &$keys = null, array &$vals = null)` | Checks if a given DN `$dn` is malformed. If `$keys` or `$keys` and `$vals` are given, these arrays will be filled with the appropriate DN keys and values. This method is deprecated, please use `Zend_Ldap_Dn::checkDn()` instead.
`__construct($options)` | Constructor. The `$options` parameter is optional and can be set to an array or a `Zend_Config` instance. If no options are provided at instantiation, the connection parameters must be passed to the instance using `Zend_Ldap::setOptions()`. The allowed options are specified in Zend_Ldap Options
`resource getResource()` | Returns the raw LDAP extension (ext/ldap) resource.
`integer getLastErrorCode()` | Returns the LDAP error number of the last LDAP command.

`string getLastError(integer &$errorCode, array &$errorMessages)`

Returns the LDAP error message of the last LDAP command. The optional `$errorCode` parameter is set to the LDAP error number when given. The optional `$errorMessages` array will be filled with the raw error messages when given. The various LDAP error retrieval functions can return different things, so they are all collected if `$errorMessages` is given.

`Zend_Ldap setOptions($options)` | Sets the LDAP connection and binding parameters. `$options` can be an array or an instance of `Zend_Config`. The allowed options are specified in Zend_Ldap Options
`array getOptions()` | Returns the current connection and binding parameters.
`string getBaseDn()` | Returns the base DN this LDAP connection is bound to.
`string getCanonicalAccountName(string $acctname, integer $form)` | Returns the canonical account name of the given account name `$acctname`. `$form` specifies the format into which the account name is canonicalized. See Account Name Canonicalization for more details.
`Zend_Ldap disconnect()` | Disconnects the Zend_Ldap instance from the LDAP server.
`Zend_Ldap connect(string $host, integer $port, boolean $useSsl, boolean $useStartTls)` | Connects the Zend_Ldap instance to the given LDAP server. All parameters are optional and will be taken from the LDAP connection and binding parameters passed to the instance via the construtor or via `Zend_Ldap::setOptions()` when set to `NULL`.

`Zend_Ldap bind(string $username, string $password)`

Authenticates `$username` with `$password` at the LDAP server. If both paramaters are omitted the binding will be carried out with the credentials given in the connection and binding parameters. If no credentials are given in the connection and binding parameters an anonymous bind will be performed. Note that this requires anonymous binds to be allowed on the LDAP server. An empty string `''` can be passed as `$password` together with a username if, and only if, `allowEmptyPassword` is set to `TRUE` in the connection and binding parameters.

`Zend_Ldap_Collection search(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string $sort, string $collectionClass)`

Searches the LDAP tree with the given `$filter` and the given search parameters.

`string|Zend_Ldap_Filter_Abstract $filter`

  The filter string to be used in the search, e.g. `(objectClass=posixAccount)`.

`string|Zend_Ldap_Dn $basedn`

  The search base for the search. If omitted or `NULL`, the `baseDn` from the connection and binding parameters is used.

`integer $scope`

  The search scope. `Zend_Ldap::SEARCH_SCOPE_SUB` searches the complete subtree including the `$baseDn` node. `Zend_Ldap::SEARCH_SCOPE_ONE` restricts search to one level below `$baseDn`. `Zend_Ldap::SEARCH_SCOPE_BASE` restricts search to the `$baseDn` itself; this can be used to efficiently retrieve a single entry by its DN. The default value is `Zend_Ldap::SEARCH_SCOPE_SUB`.

`array $attributes`

  Specifies the attributes contained in the returned entries. To include all possible attributes (ACL restrictions can disallow certain attribute to be retrieved by a given user) pass either an empty array `array()` or `array('*')` to the method. On some LDAP servers you can retrieve special internal attributes by passing `array('*', '+')` to the method.

`string $sort`

  If given the result collection will be sorted after the attribute `$sort`. Results can only be sorted after one single attribute as this parameter uses the ext/ldap function `ldap_sort()`.

`string $collectionClass`

  If given the result will be wrapped in an object of type `$collectionClass`. By default an object of type `Zend_Ldap_Collection` will be returned. The custom class must extend `Zend_Ldap_Collection` and will be passed a `Zend_Ldap_Collection_Iterator_Default` on instantiation.

`integer count(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope)` | Counts the elements returned by the given search parameters. See `Zend_Ldap::search()` for a detailed description of the method parameters.
`integer countChildren(string|Zend_Ldap_Dn $dn)` | Counts the direct descendants (children) of the entry identified by the given `$dn`.
`boolean exists(string|Zend_Ldap_Dn $dn)` | Checks whether the entry identified by the given `$dn` exists.
`array searchEntries(string|Zend_Ldap_Filter_Abstract $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string $sort)` | Performs a search operation and returns the result as an PHP array. This is essentially the same method as `Zend_Ldap::search()` except for the return type. See `Zend_Ldap::search()` for a detailed description of the method parameters.

`array getEntry(string|Zend_Ldap_Dn $dn, array $attributes, boolean $throwOnNotFound)`

Retrieves the LDAP entry identified by `$dn` with the attributes specified in `$attributes`. If `$attributes` is ommitted, all attributes (`array()`) are included in the result. `$throwOnNotFound` is `FALSE` by default, so the method will return `NULL` if the specified entry cannot be found. If set to `TRUE`, a `Zend_Ldap_Exception` will be thrown instead.

`void prepareLdapEntryArray(array &$entry)` | Prepare an array for the use in LDAP modification operations. This method does not need to be called by the end-user as it's implicitly called on every data modification method.
`Zend_Ldap add(string|Zend_Ldap_Dn $dn, array $entry)` | Adds the entry identified by `$dn` with its attributes `$entry` to the LDAP tree. Throws a `Zend_Ldap_Exception` if the entry could not be added.
`Zend_Ldap update(string|Zend_Ldap_Dn $dn, array $entry)` | Updates the entry identified by `$dn` with its attributes `$entry` to the LDAP tree. Throws a `Zend_Ldap_Exception` if the entry could not be modified.
`Zend_Ldap save(string|Zend_Ldap_Dn $dn, array $entry)` | Saves the entry identified by `$dn` with its attributes `$entry` to the LDAP tree. Throws a `Zend_Ldap_Exception` if the entry could not be saved. This method decides by querying the LDAP tree if the entry will be added or updated.

`Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean $recursively)`

Deletes the entry identified by `$dn` from the LDAP tree. Throws a `Zend_Ldap_Exception` if the entry could not be deleted. `$recursively` is `FALSE` by default. If set to `TRUE` the deletion will be carried out recursively and will effectively delete a complete subtree. Deletion will fail if `$recursively` is `FALSE` and the entry `$dn` is not a leaf entry.

`Zend_Ldap moveToSubtree(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)`

Moves the entry identified by `$from` to a location below `$to` keeping its RDN unchanged. `$recursively` specifies if the operation will be carried out recursively (`FALSE` by default) so that the entry `$from` and all its descendants will be moved. Moving will fail if `$recursively` is `FALSE` and the entry `$from` is not a leaf entry. `$alwaysEmulate` controls whether the ext/ldap function `ldap_rename()` should be used if available. This can only work for leaf entries and for servers and for ext/ldap supporting this function. Set to `TRUE` to always use an emulated rename operation.

All move-operations are carried out by copying and then deleting the corresponding entries in the LDAP tree. These operations are not atomic so that failures during the operation will result in an inconsistent state on the LDAP server. The same is true for all recursive operations. They also are by no means atomic. Please keep this in mind.

`Zend_Ldap move(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)` | This is an alias for `Zend_Ldap::rename()`.

`Zend_Ldap rename(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively, boolean $alwaysEmulate)`

Renames the entry identified by `$from` to `$to`. `$recursively` specifies if the operation will be carried out recursively (`FALSE` by default) so that the entry `$from` and all its descendants will be moved. Moving will fail if `$recursively` is `FALSE` and the entry `$from` is not a leaf entry. `$alwaysEmulate` controls whether the ext/ldap function `ldap_rename()` should be used if available. This can only work for leaf entries and for servers and for ext/ldap supporting this function. Set to `TRUE` to always use an emulated rename operation.

`Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively)`

Copies the entry identified by `$from` to a location below `$to` keeping its RDN unchanged. `$recursively` specifies if the operation will be carried out recursively (`FALSE` by default) so that the entry `$from` and all its descendants will be copied. Copying will fail if `$recursively` is `FALSE` and the entry `$from` is not a leaf entry.

`Zend_Ldap copy(string|Zend_Ldap_Dn $from, string|Zend_Ldap_Dn $to, boolean $recursively)` | Copies the entry identified by `$from` to `$to`. `$recursively` specifies if the operation will be carried out recursively (`FALSE` by default) so that the entry `$from` and all its descendants will be copied. Copying will fail if `$recursively` is `FALSE` and the entry `$from` is not a leaf entry.
`Zend_Ldap_Node getNode(string|Zend_Ldap_Dn $dn)` | Returns the entry `$dn` wrapped in a `Zend_Ldap_Node`.
`Zend_Ldap_Node getBaseNode()` | Returns the entry for the base DN `$baseDn` wrapped in a `Zend_Ldap_Node`.
`Zend_Ldap_Node_RootDse getRootDse()` | Returns the RootDSE for the current server.
`Zend_Ldap_Node_Schema getSchema()` | Returns the LDAP schema for the current server.

## Zend_Ldap_Collection

`Zend_Ldap_Collection` implements `Iterator` to allow for item traversal using `foreach()` and `Countable` to be able to respond to `count()`. With its protected `_createEntry()` method it provides a simple extension point for developers needing custom result objects.

### Zend_Ldap_Collection API

Method | Description
--- | ---
`__construct(Zend_Ldap_Collection_Iterator_Interface $iterator)` | Constructor. The constrcutor must be provided by a `Zend_Ldap_Collection_Iterator_Interface` which does the real result iteration. `Zend_Ldap_Collection_Iterator_Default` is the default implementation for iterating ext/ldap results.
`boolean close()` | Closes the internal iterator. This is also called in the destructor.
`array toArray()` | Returns all entries as an array.
`array getFirst()` | Returns the first entry in the collection or `NULL` if the collection is empty.