Documentation

Horde_Ldap_Search
in package
implements Iterator

Result set of an LDAP search

Copyright 2009 Jan Wagner, Benedikt Hallinger Copyright 2010-2017 Horde LLC (http://www.horde.org/)

Tags
category

Horde

author

Tarjej Huse tarjei@bergfald.no

author

Benedikt Hallinger beni@php.net

author

Jan Schneider jan@horde.org

license

http://www.gnu.org/licenses/lgpl-3.0.html LGPL-3.0

Interfaces, Classes, Traits and Enums

Iterator

Table of Contents

$_entry  : resource
Result entry identifier.
$_entry_cache  : array<string|int, mixed>
Cache variable for storing entries fetched internally.
$_errorCode  : int
The errorcode from the search.
$_iteratorCache  : array<string|int, mixed>
Cache for all entries already fetched from iterator interface.
$_ldap  : Horde_Ldap
Horde_Ldap object.
$_link  : resource
LDAP resource link.
$_search  : resource
Search result identifier.
$_searchedAttrs  : array<string|int, mixed>
Attributes we searched for.
__construct()  : mixed
Constructor.
__destruct()  : mixed
Destructor.
asArray()  : array<string|int, mixed>
Returns entries as array.
count()  : int
Returns the number of entries in the search result.
current()  : Horde_Ldap_Entry|false
SPL Iterator interface: Returns the current element.
entries()  : array<string|int, mixed>
Returns all entries from the search result.
getErrorCode()  : int
Returns the errorcode from the search.
key()  : string|false
SPL Iterator interface: Returns the identifying key (DN) of the current entry.
next()  : mixed
SPL Iterator interface: Moves forward to next entry.
popEntry()  : Horde_Ldap_Entry|false
Retrieve the next entry in the search result, but starting from last entry.
rewind()  : mixed
SPL Iterator interface: Rewinds the Iterator to the first element.
setLink()  : mixed
Sets the LDAP resource link.
setSearch()  : mixed
Sets the search objects resource link
shiftEntry()  : Horde_Ldap_Entry|false
Get the next entry from the search result.
sizeLimitExceeded()  : bool
Returns wheter this search exceeded a sizelimit.
sorted()  : array<string|int, mixed>
Returns entries sorted as objects.
sortedAsArray()  : array<string|int, mixed>
Return entries sorted as array.
valid()  : bool
SPL Iterator interface: Checks if there is a current element after calls to {@link rewind()} or {@link next()}.
searchedAttributes()  : array<string|int, mixed>
Returns the attribute names this search selected.

Properties

$_entry

Result entry identifier.

protected resource $_entry

$_entry_cache

Cache variable for storing entries fetched internally.

protected array<string|int, mixed> $_entry_cache = \false

This currently is only used by .

$_errorCode

The errorcode from the search.

protected int $_errorCode = 0

Some errorcodes might be of interest that should not be considered errors, for example:

  • 4: LDAP_SIZELIMIT_EXCEEDED - indicates a huge search. Incomplete results are returned. If you just want to check if there is anything returned by the search at all, this could be catched.
  • 32: no such object - search here returns a count of 0.

$_iteratorCache

Cache for all entries already fetched from iterator interface.

protected array<string|int, mixed> $_iteratorCache = array()

$_ldap

Horde_Ldap object.

protected Horde_Ldap $_ldap

A reference of the Horde_Ldap object for passing to Horde_Ldap_Entry.

$_link

LDAP resource link.

protected resource $_link

$_search

Search result identifier.

protected resource $_search

$_searchedAttrs

Attributes we searched for.

protected array<string|int, mixed> $_searchedAttrs = array()

This variable gets set from the constructor and can be retrieved through .

Methods

__construct()

Constructor.

public __construct(resource $search, Horde_Ldap|resource $ldap[, array<string|int, mixed> $attributes = array() ]) : mixed
Parameters
$search : resource

Search result identifier.

$ldap : Horde_Ldap|resource

Horde_Ldap object or a LDAP link resource

$attributes : array<string|int, mixed> = array()

The searched attribute names, see .

Return values
mixed —

__destruct()

Destructor.

public __destruct() : mixed
Return values
mixed —

asArray()

Returns entries as array.

public asArray() : array<string|int, mixed>

The first array level contains all found entries where the keys are the DNs of the entries. The second level arrays contian the entries attributes such that the keys is the lowercased name of the attribute and the values are stored in another indexed array. Note that the attribute values are stored in an array even if there is no or just one value.

The array has the following structure: array( 'cn=foo,dc=example,dc=com' => array( 'sn' => array('foo'), 'multival' => array('val1', 'val2', 'valN')), 'cn=bar,dc=example,dc=com' => array( 'sn' => array('bar'), 'multival' => array('val1', 'valN')))

Tags
throws
Horde_Ldap_Exception
Return values
array<string|int, mixed> —

Associative result array as described above.

count()

Returns the number of entries in the search result.

public count() : int
Return values
int —

Number of found entries.

current()

SPL Iterator interface: Returns the current element.

public current() : Horde_Ldap_Entry|false

The SPL Iterator interface allows you to fetch entries inside a foreach() loop: foreach ($search as $dn => $entry) { ...

Of course, you may call , , , and yourself.

If the search throwed an error, it returns false. False is also returned, if the end is reached.

In case no call to next() was made, we will issue one, thus returning the first entry.

Tags
throws
Horde_Ldap_Exception
Return values
Horde_Ldap_Entry|false —

entries()

Returns all entries from the search result.

public entries() : array<string|int, mixed>
Tags
throws
Horde_Ldap_Exception
Return values
array<string|int, mixed> —

All entries.

getErrorCode()

Returns the errorcode from the search.

public getErrorCode() : int
Return values
int —

The LDAP error number.

key()

SPL Iterator interface: Returns the identifying key (DN) of the current entry.

public key() : string|false
Tags
see
current()
Return values
string|false —

DN of the current entry; false in case no entry is returned by current().

next()

SPL Iterator interface: Moves forward to next entry.

public next() : mixed

After a call to , will return the next entry in the result set.

Tags
see
current()
throws
Horde_Ldap_Exception
Return values
mixed —

rewind()

SPL Iterator interface: Rewinds the Iterator to the first element.

public rewind() : mixed

After rewinding, will return the first entry in the result set.

Tags
see
current()
Return values
mixed —

setLink()

Sets the LDAP resource link.

public setLink(resource $link) : mixed
Parameters
$link : resource

LDAP link identifier.

Return values
mixed —

setSearch()

Sets the search objects resource link

public setSearch(resource $search) : mixed
Parameters
$search : resource

Search result identifier.

Return values
mixed —

shiftEntry()

Get the next entry from the search result.

public shiftEntry() : Horde_Ldap_Entry|false

This will return a valid Horde_Ldap_Entry object or false, so you can use this method to easily iterate over the entries inside a while loop.

Tags
throws
Horde_Ldap_Exception
Return values
Horde_Ldap_Entry|false —

Reference to Horde_Ldap_Entry object or false if no more entries exist.

sizeLimitExceeded()

Returns wheter this search exceeded a sizelimit.

public sizeLimitExceeded() : bool
Return values
bool —

True if the size limit was exceeded.

sorted()

Returns entries sorted as objects.

public sorted([array<string|int, mixed> $attrs = array('cn') ][, int $order = SORT_ASC ]) : array<string|int, mixed>

This returns a array with sorted Horde_Ldap_Entry objects. The sorting is actually done with .

Please note that attribute names are case sensitive!

Also note that it is (depending on server capabilities) possible to let the server sort your results. This happens through search controls and is described in detail at

Usage example: // To sort entries first by location, then by surname, but descending: $entries = $search->sorted(array('locality', 'sn'), SORT_DESC);

Parameters
$attrs : array<string|int, mixed> = array('cn')

Attribute names as sort criteria.

$order : int = SORT_ASC

Ordering direction, either constant SORT_ASC or SORT_DESC

Tags
todo

Entry object construction could be faster. Maybe we could use one of the factories instead of fetching the entry again.

throws
Horde_Ldap_Exception
Return values
array<string|int, mixed> —

Sorted entries.

sortedAsArray()

Return entries sorted as array.

public sortedAsArray([array<string|int, mixed> $attrs = array('cn') ][, int $order = SORT_ASC ]) : array<string|int, mixed>

This returns a array with sorted entries and the values. Sorting is done with PHPs .

This method relies on to fetch the raw data of the entries.

Please note that attribute names are case sensitive!

Usage example: // To sort entries first by location, then by surname, but descending: $entries = $search->sortedAsArray(array('locality', 'sn'), SORT_DESC);

Parameters
$attrs : array<string|int, mixed> = array('cn')

Attribute names as sort criteria.

$order : int = SORT_ASC

Ordering direction, either constant SORT_ASC or SORT_DESC

Tags
todo

what about server side sorting as specified in http://www.ietf.org/rfc/rfc2891.txt?

todo

Nuke evil eval().

throws
Horde_Ldap_Exception
Return values
array<string|int, mixed> —

Sorted entries.

valid()

SPL Iterator interface: Checks if there is a current element after calls to {@link rewind()} or {@link next()}.

public valid() : bool

Used to check if we've iterated to the end of the collection.

Tags
see
current()
Return values
bool —

False if there's nothing more to iterate over.

searchedAttributes()

Returns the attribute names this search selected.

protected searchedAttributes() : array<string|int, mixed>
Tags
see

$_searchedAttrs

Return values
array<string|int, mixed> —

Search results