# Zend_Ldap_Dn

`Zend_Ldap_Dn` provides an object-oriented interface to manipulating LDAP distinguished names (DN). The parameter `$caseFold` that is used in several methods determines the way DN attributes are handled regarding their case. Allowed values for this paraneter are:

`Zend_Ldap_Dn::ATTR_CASEFOLD_NONE`

  No case-folding will be done.

`Zend_Ldap_Dn::ATTR_CASEFOLD_UPPER`

  All attributes will be converted to upper-case.

`Zend_Ldap_Dn::ATTR_CASEFOLD_LOWER`

  All attributes will be converted to lower-case.

The default case-folding is `Zend_Ldap_Dn::ATTR_CASEFOLD_NONE` and can be set with `Zend_Ldap_Dn::setDefaultCaseFold()`. Each instance of `Zend_Ldap_Dn` can have its own case-folding-setting. If the `$caseFold` parameter is ommitted in method-calls it defaults to the instance's case-folding setting.

The class implements `ArrayAccess` to allow indexer-access to the different parts of the DN. The `ArrayAccess`-methods proxy to `Zend_Ldap_Dn::get($offset, 1, null)` for `offsetGet(integer $offset)`, to `Zend_Ldap_Dn::set($offset, $value)` for `offsetSet()` and to `Zend_Ldap_Dn::remove($offset, 1)` for `offsetUnset()`. `offsetExists()` simply checks if the index is within the bounds.

## Zend_Ldap_Dn API

Method | Description
--- | ---
`Zend_Ldap_Dn factory(string|array $dn, string|null $caseFold)` | Creates a `Zend_Ldap_Dn` instance from an array or a string. The array must conform to the array structure detailed under `Zend_Ldap_Dn::implodeDn()`.
`Zend_Ldap_Dn fromString(string $dn, string|null $caseFold)` | Creates a `Zend_Ldap_Dn` instance from a string.
`Zend_Ldap_Dn fromArray(array $dn, string|null $caseFold)` | Creates a `Zend_Ldap_Dn` instance from an array. The array must conform to the array structure detailed under `Zend_Ldap_Dn::implodeDn()`.
`array getRdn(string|null $caseFold)` | Gets the RDN of the current DN. The return value is an array with the RDN attribute names its keys and the RDN attribute values.
`string getRdnString(string|null $caseFold)` | Gets the RDN of the current DN. The return value is a string.
`Zend_Ldap_Dn getParentDn(integer $levelUp)` | Gets the DN of the current DN's ancestor `$levelUp` levels up the tree. `$levelUp` defaults to `1`.
`array get(integer $index, integer $length, string|null $caseFold)` | Returns a slice of the current DN determined by `$index` and `$length`. `$index` starts with `0` on the DN part from the left.
`Zend_Ldap_Dn set(integer $index, array $value)` | Replaces a DN part in the current DN. This operation manipulates the current instance.
`Zend_Ldap_Dn remove(integer $index, integer $length)` | Removes a DN part from the current DN. This operation manipulates the current instance. `$length` defaults to `1`
`Zend_Ldap_Dn append(array $value)` | Appends a DN part to the current DN. This operation manipulates the current instance.
`Zend_Ldap_Dn prepend(array $value)` | Prepends a DN part to the current DN. This operation manipulates the current instance.
`Zend_Ldap_Dn insert(integer $index, array $value)` | Inserts a DN part after the index `$index` to the current DN. This operation manipulates the current instance.
`void setCaseFold(string|null $caseFold)` | Sets the case-folding option to the current DN instance. If `$caseFold` is null the default case-folding setting (`Zend_Ldap_Dn::ATTR_CASEFOLD_NONE` by default or set via `Zend_Ldap_Dn::setDefaultCaseFold()` will be set for the current instance.
`string toString(string|null $caseFold)` | Returns DN as a string.
`array toArray(string|null $caseFold)` | Returns DN as an array.
`string __toString()` | Returns DN as a string - proxies to `Zend_Ldap_Dn::toString(null)`.
`void setDefaultCaseFold(string $caseFold)` | Sets the default case-folding option used by all instances on creation by default. Already existing instances are not affected by this setting.
`array escapeValue(string|array $values)` | Escapes a DN value according to RFC 2253.
`array unescapeValue(string|array $values)` | Undoes the conversion done by `Zend_Ldap_Dn::escapeValue()`.

`array explodeDn(string $dn, array &$keys, array &$vals, string|null $caseFold)`

Explodes the DN `$dn` into an array containing all parts of the given DN. `$keys` optinally receive DN keys (e.g. CN, OU, DC, ...). `$vals` optionally receive DN values. The resulting array will be of type

    array(
    array("cn" => "name1", "uid" => "user"),
    array("cn" => "name2"),
    array("dc" => "example"),
    array("dc" => "org")
    )

for a DN of `cn=name1+uid=user,cn=name2,dc=example,dc=org`.

`boolean checkDn(string $dn, array &$keys, array &$vals, string|null $caseFold)` | 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.
`string implodeRdn(array $part, string|null $caseFold)` | Returns a DN part in the form `$attribute=$value`

`string implodeDn(array $dnArray, string|null $caseFold, string $separator)`

Implodes an array in the form delivered by `Zend_Ldap_Dn::explodeDn()` to a DN string. `$separator` defaults to `','` but some LDAP servers also understand `';'`. `$dnArray` must of type

    array(
    array("cn" => "name1", "uid" => "user"),
    array("cn" => "name2"),
    array("dc" => "example"),
    array("dc" => "org")
    )

`boolean isChildOf(string|Zend_Ldap_Dn $childDn, string|Zend_Ldap_Dn $parentDn)` | Checks if given `$childDn` is beneath `$parentDn` subtree.