PHP Class Horde_Ldap, horde

Author: Tarjej Huse ([email protected])

Author: Jan Wagner ([email protected])

Author: Del ([email protected])

Author: Benedikt Hallinger ([email protected])

Author: Ben Klang ([email protected])

Author: Chuck Hagenbuch ([email protected])

Author: Jan Schneider ([email protected])

Exibir arquivo Open project: horde/horde Class Usage Examples

Protected Properties

Property	Type	Description
$_config	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 {@link 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.
$_downHostList	array	List of hosts that are known to be down.
$_hostList	array	List of hosts we try to establish a connection to.
$_link	resource	LDAP resource link.
$_rootDSECache	array	Hash with requested rootDSE attr names as key and rootDSE object as value. Since the RootDSE object itself may request a rootDSE object, {@link rootDSE()} caches successful requests. Internally, Horde_Ldap needs several lookups to this object, so caching increases performance significally.
$_schema	Horde_Ldap_Schema	Schema object.
$_schemaAttrs		Cache for attribute encoding checks.
$_schemaCache	string	Schema cache function callback.

Public Methods

Method	Description
__construct ( array $config = [] )	Constructor.
__destruct ( )	Destructor.
add ( Horde_Ldap_Entry $entry )	Adds a new entry to the directory.
bind ( string $dn = null, string $password = null )	Bind or rebind to the LDAP server.
buildClause ( string $lhs, string $op, string $rhs, array $params = [] ) : string	Builds an LDAP search filter fragment.
checkLDAPExtension ( )	Checks if PHP's LDAP extension is loaded.
copy ( Horde_Ldap_Entry $entry, string $newdn ) : Horde_Ldap_Entry	Copies an entry to a new location.
delete ( string \| Horde_Ldap_Entry $dn, boolean $recursive = false )	Deletes an entry from the directory.
disconnect ( )	Closes the LDAP connection.
errorName ( integer $errorcode ) : string	Returns the string for an LDAP errorcode.
exists ( string \| Horde_Ldap_Entry $dn ) : boolean	Returns whether a DN exists in the directory.
findUserDN ( string $user ) : string	Returns the DN of a user.
getEntry ( string $dn, array $attributes = [] ) : Horde_Ldap_Entry	Returns a specific entry based on the DN.
getLink ( ) : resource	Returns the LDAP link resource.
getOption ( string $option ) : Horde_Ldap_Error \| string	Returns an LDAP option value.
getVersion ( ) : integer	Returns the LDAP protocol version that is used on the connection.
modify ( string \| Horde_Ldap_Entry $entry, array $parms = [] )	Modifies an LDAP entry on the server.
move ( string \| Horde_Ldap_Entry $entry, string $newdn, Horde_Ldap $target_ldap = null )	Renames or moves an entry.
quote ( string $clause ) : string	Escapes characters with special meaning in LDAP searches.
quoteDN ( array $parts ) : string	Takes an array of DN elements and properly quotes it according to RFC 1485.
rootDSE ( array $attrs = [] ) : Horde_Ldap_RootDse	Returns a rootDSE object
schema ( string $dn = null ) : Horde_Ldap_Schema	Returns a schema object
search ( string \| Horde_Ldap_Entry $base = null, string \| Horde_Ldap_Filter $filter = null, array $params = [] ) : Horde_Ldap_Search	Runs an LDAP search query.
setOption ( string $option, mixed $value )	Sets an LDAP option.
setVersion ( integer $version, boolean $force = false )	Sets the LDAP protocol version that is used on the connection.
startTLS ( )	Starts an encrypted session.
utf8Decode ( array $attributes ) : array \| Horde_Ldap_Error
utf8Encode ( array $attributes ) : array \| Horde_Ldap_Error

Protected Methods

Method	Description
_connect ( )	Connects to the LDAP server.
_quoteRDN ( array $attribute ) : string	Takes an RDN array with an attribute name and value and properly quotes it according to RFC 1485.
_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.
_reconnect ( )	Reconnects to the LDAP server.
setConfig ( array $config )	Sets the internal configuration array.
utf8 ( array $attributes, array $function ) : array

Method Details

__construct() public method

Constructor.

public __construct ( array $config = [] )
$config	array	Configuration array.

__destruct() public method

Destructor.

public __destruct ( )

_connect() protected method

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

protected _connect ( )

_quoteRDN() protected static method

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

protected static _quoteRDN ( array $attribute ) : string
$attribute	array	A tuple containing the attribute name and that attribute's value which make up the RDN.
return	string	The properly quoted string RDN.

_quoteRDNs() protected static method

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

protected static _quoteRDNs ( array $attribute ) : string
$attribute	array	A tuple or array of tuples containing the attribute name and that attribute's value which make up the RDN.
return	string	The properly quoted string RDN.

_reconnect() protected method

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.

protected _reconnect ( )

add() public method

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

See also: HordeLdap_Entry::createFresh()

public add ( Horde_Ldap_Entry $entry )
$entry	Horde_Ldap_Entry	An LDAP entry.

bind() public method

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.

public bind ( string $dn = null, string $password = null )
$dn	string	DN for binding.
$password	string	Password for binding.

buildClause() public static method

Builds an LDAP search filter fragment.

public static buildClause ( string $lhs, string $op, string $rhs, array $params = [] ) : string
$lhs	string	The attribute to test.
$op	string	The operator.
$rhs	string	The comparison value.
$params	array	Any additional parameters for the operator.
return	string	The LDAP search fragment.

checkLDAPExtension() public static method

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

public static checkLDAPExtension ( )

copy() public method

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

public copy ( Horde_Ldap_Entry $entry, string $newdn ) : Horde_Ldap_Entry
$entry	Horde_Ldap_Entry	An LDAP entry.
$newdn	string	New FQF-DN of the entry.
return	Horde_Ldap_Entry	The copied entry.

delete() public method

Deletes an entry from the directory.

public delete ( string \| Horde_Ldap_Entry $dn, boolean $recursive = false )
$dn	string \| Horde_Ldap_Entry	DN string or Horde_Ldap_Entry.
$recursive	boolean	Should we delete all children recursivelx as well?

disconnect() public method

Closes the LDAP connection.

public disconnect ( )

errorName() public static method

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

public static errorName ( integer $errorcode ) : string
$errorcode	integer	An error code.
return	string	The description for the error.

exists() public method

Returns whether a DN exists in the directory.

public exists ( string \| Horde_Ldap_Entry $dn ) : boolean
$dn	string \| Horde_Ldap_Entry	The DN of the object to test.
return	boolean	True if the DN exists.

findUserDN() public method

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.

public findUserDN ( string $user ) : string
$user	string	The user to find.
return	string	The user's full DN.

getEntry() public method

Returns a specific entry based on the DN.

public getEntry ( string $dn, array $attributes = [] ) : Horde_Ldap_Entry
$dn	string	DN of the entry that should be fetched.
$attributes	array	Array of Attributes to select. If ommitted, all attributes are fetched.
return	Horde_Ldap_Entry	A Horde_Ldap_Entry object.

getLink() public method

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).

public getLink ( ) : resource
return	resource	LDAP link.

getOption() public method

Returns an LDAP option value.

public getOption ( string $option ) : Horde_Ldap_Error \| string
$option	string	Option to get.
return	Horde_Ldap_Error \| string	Horde_Ldap_Error or option value

getVersion() public method

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

public getVersion ( ) : integer
return	integer	The protocol version.

modify() public method

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.

move() public method

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.

public move ( string \| Horde_Ldap_Entry $entry, string $newdn, Horde_Ldap $target_ldap = null )
$entry	string \| Horde_Ldap_Entry	An LDAP entry.
$newdn	string	The new location.
$target_ldap	Horde_Ldap	Target directory for cross server move.

quote() public static method

Escapes characters with special meaning in LDAP searches.

public static quote ( string $clause ) : string
$clause	string	The string to escape.
return	string	The escaped string.

quoteDN() public static method

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

public static quoteDN ( array $parts ) : string
$parts	array	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
return	string	The properly quoted string DN.

rootDSE() public method

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

public rootDSE ( array $attrs = [] ) : Horde_Ldap_RootDse
$attrs	array	Array of attributes to search for.
return	Horde_Ldap_RootDse	Horde_Ldap_RootDse object

schema() public method

Returns a schema object

public schema ( string $dn = null ) : Horde_Ldap_Schema
$dn	string	Subschema entry dn.
return	Horde_Ldap_Schema	Horde_Ldap_Schema object

search() public method

$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.

public search ( string \| Horde_Ldap_Entry $base = null, string \| Horde_Ldap_Filter $filter = null, array $params = [] ) : Horde_Ldap_Search
$base	string \| Horde_Ldap_Entry	LDAP searchbase.
$filter	string \| Horde_Ldap_Filter	LDAP search filter.
$params	array	Array of options.
return	Horde_Ldap_Search	The search result.

setConfig() protected method

Sets the internal configuration array.

protected setConfig ( array $config )
$config	array	Configuration hash.

setOption() public method

Sets an LDAP option.

public setOption ( string $option, mixed $value )
$option	string	Option to set.
$value	mixed	Value to set option to.

setVersion() public method

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

public setVersion ( integer $version, boolean $force = false )
$version	integer	LDAP version that should be used.
$force	boolean	If set to true, the check against the rootDSE will be skipped.

startTLS() public method

Starts an encrypted session.

public startTLS ( )

utf8() protected method

protected utf8 ( array $attributes, array $function ) : array
$attributes	array	Array of attributes
$function	array	Function to apply to attribute values
return	array	Array of attributes with function applied to values.

utf8Decode() public method

utf8Encode() public method

public utf8Encode ( array $attributes ) : array \| Horde_Ldap_Error
$attributes	array	An array of attributes.
return	array \| Horde_Ldap_Error	An array of UTF8 encoded attributes or an error.

Property Details

$_config protected_oe property

- 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 {@link 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.

protected array $_config
return	array

$_downHostList protected_oe property

List of hosts that are known to be down.

protected array $_downHostList
return	array

$_hostList protected_oe property

List of hosts we try to establish a connection to.

protected array $_hostList
return	array

$_link protected_oe property

LDAP resource link.

protected resource $_link
return	resource

$_rootDSECache protected_oe property

Hash with requested rootDSE attr names as key and rootDSE object as value. Since the RootDSE object itself may request a rootDSE object, {@link rootDSE()} caches successful requests. Internally, Horde_Ldap needs several lookups to this object, so caching increases performance significally.

protected array $_rootDSECache
return	array

$_schema protected_oe property

Schema object.

$_schemaAttrs protected_oe property

Cache for attribute encoding checks.

protected $_schemaAttrs

$_schemaCache protected_oe property

Schema cache function callback.

public modify ( string \| Horde_Ldap_Entry $entry, array $parms = [] )
$entry	string \| Horde_Ldap_Entry	DN string or Horde_Ldap_Entry.
$parms	array	Array of changes

public utf8Decode ( array $attributes ) : array \| Horde_Ldap_Error
$attributes	array	Array of attributes
return	array \| Horde_Ldap_Error	Array with decoded attribute values or Error