API Documentation
\

\Horde_Ldap

The main Horde_Ldap class.

Copyright 2003-2007 Tarjej Huse, Jan Wagner, Del Elson, Benedikt Hallinger Copyright 2009-2017 Horde LLC (http://www.horde.org/)

Summary

Methods
Properties
Constants
__construct()
__destruct()
bind()
disconnect()
startTLS()
add()
delete()
modify()
search()
findUserDN()
setOption()
getOption()
getVersion()
setVersion()
exists()
getEntry()
move()
copy()
errorName()
rootDSE()
schema()
checkLDAPExtension()
utf8Encode()
utf8Decode()
getLink()
buildClause()
quote()
quoteDN()
No public properties found
No constants found
setConfig()
_connect()
_reconnect()
utf8()
_quoteRDNs()
_quoteRDN()
$_config
$_hostList
$_downHostList
$_link
$_schema
$_schemaAttrs
$_rootDSE
N/A
No private methods found
No private properties found
N/A

Properties

$_config

$_config : array

Class configuration array.

  • hostspec: The LDAP host to connect to (may be an array of several hosts to try).
  • port: The server port.
  • version: LDAP version (defaults to 3).
  • tls: When set, ldap_start_tls() is run after connecting.
  • binddn: The DN to bind as when searching.
  • bindpw: Password to use when searching LDAP.
  • basedn: LDAP base.
  • options: Hash of LDAP options to set.
  • filter: Default search filter.
  • scope: Default search scope.
  • user: Configuration parameters for \findUserDN(), must contain 'uid', and may contain 'basedn' entries.
  • timeout: Connection timeout in seconds (defaults to 5).
  • auto_reconnect: If true, the class will automatically attempt to reconnect to the LDAP server in certain failure conditions when attempting a search, or other LDAP operations. Defaults to false. Note that if you set this to true, calls to search() may block indefinitely if there is a catastrophic server failure.
  • min_backoff: Minimum reconnection delay period (in seconds).
  • current_backof: Initial reconnection delay period (in seconds).
  • max_backoff: Maximum reconnection delay period (in seconds).
  • cache: A Horde_Cache instance for caching schema requests.

Type

array

$_hostList

$_hostList : array

List of hosts we try to establish a connection to.

Type

array

$_downHostList

$_downHostList : array

List of hosts that are known to be down.

Type

array

$_link

$_link : resource

LDAP resource link.

Type

resource

$_schemaAttrs

$_schemaAttrs : array

Cache for attribute encoding checks.

Type

array — Hash with attribute names as key and boolean value to determine whether they should be utf8 encoded or not.

$_rootDSE

$_rootDSE : array

Cache for rootDSE objects.

Hash with requested rootDSE attr names as key and rootDSE object as value.

Since the RootDSE object itself may request a rootDSE object, \rootDSE() caches successful requests. Internally, Horde_Ldap needs several lookups to this object, so caching increases performance significally.

Type

array

Methods

__construct()

__construct(array  $config = array())

Constructor.

Parameters

array $config

Configuration array.

__destruct()

__destruct()

Destructor.

bind()

bind(string  $dn = null, string  $password = null)

Bind or rebind to the LDAP server.

This function binds with the given DN and password to the server. In case no connection has been made yet, it will be started and STARTTLS issued if appropiate.

The internal bind configuration is not being updated, so if you call bind() without parameters, you can rebind with the credentials provided at first connecting to the server.

Parameters

string $dn

DN for binding.
string $password

Password for binding.

Throws

\Horde_Ldap_Exception

disconnect()

disconnect()

Closes the LDAP connection.

startTLS()

startTLS()

Starts an encrypted session.

Throws

\Horde_Ldap_Exception

add()

add(\Horde_Ldap_Entry  $entry)

Adds a new entry to the directory.

This also links the entry to the connection used for the add, if it was a fresh entry.

Parameters

\Horde_Ldap_Entry $entry

An LDAP entry.

Throws

\Horde_Ldap_Exception

delete()

delete(string|\Horde_Ldap_Entry  $dn, boolean  $recursive = false)

Deletes an entry from the directory.

Parameters

string|\Horde_Ldap_Entry $dn

DN string or Horde_Ldap_Entry.
boolean $recursive

Should we delete all children recursivelx as well?

Throws

\Horde_Ldap_Exception

modify()

modify(string|\Horde_Ldap_Entry  $entry, array  $parms = array())

Modifies an LDAP entry on the server.

The $params argument is an array of actions and should be something like this: array('add' => array('attribute1' => array('val1', 'val2'), 'attribute2' => array('val1')), 'delete' => array('attribute1'), 'replace' => array('attribute1' => array('val1')), 'changes' => array('add' => ..., 'replace' => ..., 'delete' => array('attribute1', 'attribute2' => array('val1')))

The order of execution is as following:

  1. adds from 'add' array
  2. deletes from 'delete' array
  3. replaces from 'replace' array
  4. changes (add, replace, delete) in order of appearance

The function calls the corresponding functions of an Horde_Ldap_Entry object. A detailed description of array structures can be found there.

Unlike the modification methods provided by the Horde_Ldap_Entry object, this method will instantly carry out an update() after each operation, thus modifying "directly" on the server.

Parameters

string|\Horde_Ldap_Entry $entry

DN string or Horde_Ldap_Entry.
array $parms

Array of changes

Throws

\Horde_Ldap_Exception

search()

search(string|\Horde_Ldap_Entry  $base = null, string|\Horde_Ldap_Filter  $filter = null, array  $params = array()) : \Horde_Ldap_Search

Runs an LDAP search query.

$base and $filter may be ommitted. The one from config will then be used. $base is either a DN-string or an Horde_Ldap_Entry object in which case its DN will be used.

$params may contain:

  • scope: The scope which will be used for searching, defaults to 'sub':
    • base: Just one entry
    • sub: The whole tree
    • one: Immediately below $base
  • sizelimit: Limit the number of entries returned (default: 0 = unlimited)
  • timelimit: Limit the time spent for searching (default: 0 = unlimited)
  • attrsonly: If true, the search will only return the attribute names
  • attributes: Array of attribute names, which the entry should contain. It is good practice to limit this to just the ones you need.

You cannot override server side limitations to sizelimit and timelimit: You can always only lower a given limit.

Parameters

string|\Horde_Ldap_Entry $base

LDAP searchbase.
string|\Horde_Ldap_Filter $filter

LDAP search filter.
array $params

Array of options.

Throws

\Horde_Ldap_Exception

Returns

\Horde_Ldap_Search —

The search result.

findUserDN()

findUserDN(string  $user) : string

Returns the DN of a user.

The purpose is to quickly find the full DN of a user so it can be used to re-bind as this user. This method requires the 'user' configuration parameter to be set.

Parameters

string $user

The user to find.

Throws

\Horde_Ldap_Exception
\Horde_Exception_NotFound

Returns

string —

The user's full DN.

setOption()

setOption(string  $option, mixed  $value)

Sets an LDAP option.

Parameters

string $option

Option to set.
mixed $value

Value to set option to.

Throws

\Horde_Ldap_Exception

getOption()

getOption(string  $option) : \Horde_Ldap_Error|string

Returns an LDAP option value.

Parameters

string $option

Option to get.

Throws

\Horde_Ldap_Exception

Returns

\Horde_Ldap_Error|string —

Horde_Ldap_Error or option value

getVersion()

getVersion() : integer

Returns the LDAP protocol version that is used on the connection.

A lot of LDAP functionality is defined by what protocol version the LDAP server speaks. This might be 2 or 3.

Returns

integer —

The protocol version.

setVersion()

setVersion(integer  $version, boolean  $force = false)

Sets the LDAP protocol version that is used on the connection.

Parameters

integer $version

LDAP version that should be used.
boolean $force

If set to true, the check against the rootDSE will be skipped.

Throws

\Horde_Ldap_Exception

exists()

exists(string|\Horde_Ldap_Entry  $dn) : boolean

Returns whether a DN exists in the directory.

Parameters

string|\Horde_Ldap_Entry $dn

The DN of the object to test.

Throws

\Horde_Ldap_Exception

Returns

boolean —

True if the DN exists.

getEntry()

getEntry(string  $dn, array  $attributes = array()) : \Horde_Ldap_Entry

Returns a specific entry based on the DN.

Parameters

string $dn

DN of the entry that should be fetched.
array $attributes

Array of Attributes to select. If ommitted, all attributes are fetched.

Throws

\Horde_Ldap_Exception
\Horde_Exception_NotFound

Returns

\Horde_Ldap_Entry —

A Horde_Ldap_Entry object.

move()

move(string|\Horde_Ldap_Entry  $entry, string  $newdn, \Horde_Ldap  $target_ldap = null)

Renames or moves an entry.

This method will instantly carry out an update() after the move, so the entry is moved instantly.

You can pass an optional Horde_Ldap object. In this case, a cross directory move will be performed which deletes the entry in the source (THIS) directory and adds it in the directory $target_ldap.

A cross directory move will switch the entry's internal LDAP reference so updates to the entry will go to the new directory.

If you want to do a cross directory move, you need to pass an Horde_Ldap_Entry object, otherwise the attributes will be empty.

Parameters

string|\Horde_Ldap_Entry $entry

An LDAP entry.
string $newdn

The new location.
\Horde_Ldap $target_ldap

Target directory for cross server move.

Throws

\Horde_Ldap_Exception

copy()

copy(\Horde_Ldap_Entry  $entry, string  $newdn) : \Horde_Ldap_Entry

Copies an entry to a new location.

The entry will be immediately copied. Only attributes you have selected will be copied.

Parameters

\Horde_Ldap_Entry $entry

An LDAP entry.
string $newdn

New FQF-DN of the entry.

Throws

\Horde_Ldap_Exception

Returns

\Horde_Ldap_Entry —

The copied entry.

errorName()

errorName(integer  $errorcode) : string

Returns the string for an LDAP errorcode.

Made to be able to make better errorhandling. Function based on DB::errorMessage().

Hint: The best description of the errorcodes is found here: http://www.directory-info.com/Ldap/LDAPErrorCodes.html

Parameters

integer $errorcode

An error code.

Returns

string —

The description for the error.

rootDSE()

rootDSE(array  $attrs = array()) : \Horde_Ldap_RootDse

Returns a rootDSE object

This either fetches a fresh rootDSE object or returns it from the internal cache for performance reasons, if possible.

Parameters

array $attrs

Array of attributes to search for.

Throws

\Horde_Ldap_Exception

Returns

\Horde_Ldap_RootDse —

Horde_Ldap_RootDse object

schema()

schema(string  $dn = null) : \Horde_Ldap_Schema

Returns a schema object

Parameters

string $dn

Subschema entry dn.

Throws

\Horde_Ldap_Exception

Returns

\Horde_Ldap_Schema —

Horde_Ldap_Schema object

checkLDAPExtension()

checkLDAPExtension()

Checks if PHP's LDAP extension is loaded.

If it is not loaded, it tries to load it manually using PHP's dl(). It knows both windows-dll and *nix-so.

Throws

\Horde_Ldap_Exception

utf8Encode()

utf8Encode(array  $attributes) : array|\Horde_Ldap_Error

Parameters

array $attributes

An array of attributes.

Returns

array|\Horde_Ldap_Error —

An array of UTF8 encoded attributes or an error.

utf8Decode()

utf8Decode(array  $attributes) : array|\Horde_Ldap_Error

Parameters

array $attributes

Array of attributes

Returns

array|\Horde_Ldap_Error —

Array with decoded attribute values or Error

getLink()

getLink() : resource

Returns the LDAP link resource.

It will loop attempting to re-establish the connection if the connection attempt fails and auto_reconnect has been turned on (see the _config array documentation).

Returns

resource —

LDAP link.

buildClause()

buildClause(string  $lhs, string  $op, string  $rhs, array  $params = array()) : string

Builds an LDAP search filter fragment.

Parameters

string $lhs

The attribute to test.
string $op

The operator.
string $rhs

The comparison value.
array $params

Any additional parameters for the operator.

Returns

string —

The LDAP search fragment.

quote()

quote(string  $clause) : string

Escapes characters with special meaning in LDAP searches.

Parameters

string $clause

The string to escape.

Returns

string —

The escaped string.

quoteDN()

quoteDN(array  $parts) : string

Takes an array of DN elements and properly quotes it according to RFC 1485.

Parameters

array $parts

An array of tuples containing the attribute name and that attribute's value which make up the DN. Example: $parts = array( array('cn', 'John Smith'), array('dc', 'example'), array('dc', 'com') ); Nested arrays are supported since 2.1.0, to form multi-valued RDNs. Example: $parts = array( array( array('cn', 'John'), array('sn', 'Smith'), array('o', 'Acme Inc.'), ), array('dc', 'example'), array('dc', 'com') ); which will result in cn=John+sn=Smith+o=Acme Inc.,dc=example,dc=com

Returns

string —

The properly quoted string DN.

setConfig()

setConfig(array  $config)

Sets the internal configuration array.

Parameters

array $config

Configuration hash.

_connect()

_connect()

Connects to the LDAP server.

This function connects to the LDAP server specified in the configuration, binds and set up the LDAP protocol as needed.

Throws

\Horde_Ldap_Exception

_reconnect()

_reconnect()

Reconnects to the LDAP server.

In case the connection to the LDAP service has dropped out for some reason, this function will reconnect, and re-bind if a bind has been attempted in the past. It is probably most useful when the server list provided to the new() or _connect() function is an array rather than a single host name, because in that case it will be able to connect to a failover or secondary server in case the primary server goes down.

This method just tries to re-establish the current connection. It will sleep for the current backoff period (seconds) before attempting the connect, and if the connection fails it will double the backoff period, but not try again. If you want to ensure a reconnection during a transient period of server downtime then you need to call this function in a loop.

Throws

\Horde_Ldap_Exception

utf8()

utf8(array  $attributes, array  $function) : array

Parameters

array $attributes

Array of attributes
array $function

Function to apply to attribute values

Returns

array —

Array of attributes with function applied to values.

_quoteRDNs()

_quoteRDNs(array  $attribute) : string

Takes a single or a list of RDN arrays with an attribute name and value and properly quotes it according to RFC 1485.

Parameters

array $attribute

A tuple or array of tuples containing the attribute name and that attribute's value which make up the RDN.

Returns

string —

The properly quoted string RDN.

_quoteRDN()

_quoteRDN(array  $attribute) : string

Takes an RDN array with an attribute name and value and properly quotes it according to RFC 1485.

Parameters

array $attribute

A tuple containing the attribute name and that attribute's value which make up the RDN.

Returns

string —

The properly quoted string RDN.