1 <?xml version="1.0" encoding="UTF-8"?>
3 <sect3 id="zend.ldap.api.reference.zend-ldap">
4 <title>Zend_Ldap</title>
7 <classname>Zend_Ldap</classname> is the base interface into a <acronym>LDAP</acronym>
8 server. It provides connection and binding methods as well as methods to operate on the
9 <acronym>LDAP</acronym> tree.
12 <table id="zend.ldap.api.reference.zend-ldap.table">
13 <title>Zend_Ldap API</title>
19 <entry>Description</entry>
25 <entry><code>string filterEscape(string $str)</code></entry>
28 Escapes a value to be used in a <acronym>LDAP</acronym> filter according to
29 <acronym>RFC</acronym> 2254. This method is <emphasis>deprecated</emphasis>,
30 please use <methodname>Zend_Ldap_Filter_Abstract::escapeValue()</methodname>
37 <code>boolean explodeDn($dn, array &$keys = null, array &$vals =
42 Checks if a given DN <varname>$dn</varname> is malformed. If
43 <varname>$keys</varname> or <varname>$keys</varname> and
44 <varname>$vals</varname> are given, these arrays will be filled with the
45 appropriate DN keys and values. This method is
46 <emphasis>deprecated</emphasis>, please use
47 <methodname>Zend_Ldap_Dn::checkDn()</methodname> instead.
52 <entry><methodname>__construct($options)</methodname></entry>
55 Constructor. The <varname>$options</varname> parameter is optional
56 and can be set to an array or a <classname>Zend_Config</classname> instance.
57 If no options are provided at instantiation, the connection
58 parameters must be passed to the instance using
59 <methodname>Zend_Ldap::setOptions()</methodname>. The allowed options are
61 linkend="zend.ldap.api.configuration.table">Zend_Ldap
67 <entry><code>resource getResource()</code></entry>
70 Returns the raw <acronym>LDAP</acronym> extension (ext/ldap) resource.
75 <entry><code>integer getLastErrorCode()</code></entry>
78 Returns the <acronym>LDAP</acronym> error number of the last
79 <acronym>LDAP</acronym> command.
85 <code>string getLastError(integer &$errorCode, array
86 &$errorMessages)</code>
90 Returns the <acronym>LDAP</acronym> error message of the last
91 <acronym>LDAP</acronym> command. The optional <varname>$errorCode</varname>
92 parameter is set to the <acronym>LDAP</acronym> error number when given. The
93 optional <varname>$errorMessages</varname> array will be filled with the raw
94 error messages when given. The various <acronym>LDAP</acronym> error
95 retrieval functions can return different things, so they are all collected
96 if <varname>$errorMessages</varname> is given.
101 <entry><code>Zend_Ldap setOptions($options)</code></entry>
104 Sets the <acronym>LDAP</acronym> connection and binding parameters.
105 <varname>$options</varname> can be an array or an instance of
106 <classname>Zend_Config</classname>. The allowed options are specified in
108 linkend="zend.ldap.api.configuration.table">Zend_Ldap Options</link>
113 <entry><code>array getOptions()</code></entry>
114 <entry>Returns the current connection and binding parameters.</entry>
118 <entry><code>string getBaseDn()</code></entry>
121 Returns the base DN this <acronym>LDAP</acronym> connection is bound
128 <code>string getCanonicalAccountName(string $acctname, integer $form)</code>
132 Returns the canonical account name of the given account name
133 <varname>$acctname</varname>. <varname>$form</varname> specifies the <link
134 linkend="zend.ldap.using.theory-of-operation.account-name-canonicalization.table">format</link>
135 into which the account name is canonicalized. See <link
136 linkend="zend.ldap.introduction.theory-of-operations.account-name-canonicalization">Account
137 Name Canonicalization</link> for more details.
142 <entry><code>Zend_Ldap disconnect()</code></entry>
145 Disconnects the <classname>Zend_Ldap</classname> instance from the
146 <acronym>LDAP</acronym> server.
152 <code>Zend_Ldap connect(string $host, integer $port, boolean $useSsl,
153 boolean $useStartTls)</code>
157 Connects the <classname>Zend_Ldap</classname> instance to the given
158 <acronym>LDAP</acronym> server. All parameters are optional and will be
159 taken from the <acronym>LDAP</acronym> connection and binding parameters
160 passed to the instance via the construtor or via
161 <methodname>Zend_Ldap::setOptions()</methodname> when set to
162 <constant>NULL</constant>.
168 <code>Zend_Ldap bind(string $username, string $password)</code>
172 Authenticates <varname>$username</varname> with
173 <varname>$password</varname> at the <acronym>LDAP</acronym> server. If both
174 paramaters are omitted the binding will be carried out with the credentials
175 given in the connection and binding parameters. If no credentials are
176 given in the connection and binding parameters an anonymous bind
177 will be performed. Note that this requires anonymous binds to be allowed
178 on the <acronym>LDAP</acronym> server. An empty string <code>''</code> can
179 be passed as <varname>$password</varname> together with a username if, and
180 only if, <code>allowEmptyPassword</code> is set to
181 <constant>TRUE</constant> in the connection and binding parameters.
187 <code>Zend_Ldap_Collection search(string|Zend_Ldap_Filter_Abstract $filter,
188 string|Zend_Ldap_Dn $basedn, integer $scope, array $attributes, string
189 $sort, string $collectionClass)</code>
193 Searches the <acronym>LDAP</acronym> tree with the given
194 <varname>$filter</varname> and the given search parameters.
198 <term><code>string|Zend_Ldap_Filter_Abstract $filter</code></term>
202 The filter string to be used in the search, e.g.
203 <code>(objectClass=posixAccount)</code>.
209 <term><code>string|Zend_Ldap_Dn $basedn</code></term>
213 The search base for the search. If omitted or
214 <constant>NULL</constant>, the <code>baseDn</code> from the
215 connection and binding parameters is used.
221 <term><code>integer $scope</code></term>
226 <constant>Zend_Ldap::SEARCH_SCOPE_SUB</constant> searches
227 the complete subtree including the
228 <varname>$baseDn</varname> node.
229 <constant>Zend_Ldap::SEARCH_SCOPE_ONE</constant> restricts
230 search to one level below <varname>$baseDn</varname>.
231 <constant>Zend_Ldap::SEARCH_SCOPE_BASE</constant> restricts
232 search to the <varname>$baseDn</varname> itself; this can be
233 used to efficiently retrieve a single entry by its DN. The
235 <constant>Zend_Ldap::SEARCH_SCOPE_SUB</constant>.
241 <term><code>array $attributes</code></term>
245 Specifies the attributes contained in the
246 returned entries. To include all possible attributes (ACL
247 restrictions can disallow certain attribute to be retrieved
248 by a given user) pass either an empty array
249 <methodname>array()</methodname> or
250 <methodname>array('*')</methodname> to the method. On some
251 <acronym>LDAP</acronym> servers you can retrieve special
252 internal attributes by passing
253 <methodname>array('*', '+')</methodname> to the method.
259 <term><code>string $sort</code></term>
263 If given the result collection will be sorted after the
264 attribute <varname>$sort</varname>. Results can only be
265 sorted after one single attribute as this parameter uses
266 the ext/ldap function <methodname>ldap_sort()</methodname>.
272 <term><code>string $collectionClass</code></term>
276 If given the result will be wrapped in an object of type
277 <varname>$collectionClass</varname>. By default an object
278 of type <classname>Zend_Ldap_Collection</classname> will be
279 returned. The custom class must extend
280 <classname>Zend_Ldap_Collection</classname> and will be
282 <classname>Zend_Ldap_Collection_Iterator_Default</classname>
293 <code>integer count(string|Zend_Ldap_Filter_Abstract
294 $filter, string|Zend_Ldap_Dn $basedn, integer
299 Counts the elements returned by the given search parameters.
300 See <methodname>Zend_Ldap::search()</methodname> for a detailed description
301 of the method parameters.
306 <entry><code>integer countChildren(string|Zend_Ldap_Dn $dn)</code></entry>
309 Counts the direct descendants (children) of the entry
310 identified by the given <varname>$dn</varname>.
315 <entry><code>boolean exists(string|Zend_Ldap_Dn $dn)</code></entry>
318 Checks whether the entry identified by the given
319 <varname>$dn</varname> exists.
325 <code>array searchEntries(string|Zend_Ldap_Filter_Abstract
326 $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array
327 $attributes, string $sort)</code>
331 Performs a search operation and returns the result as an
332 <acronym>PHP</acronym> array. This is essentially the same method as
333 <methodname>Zend_Ldap::search()</methodname> except for the return type. See
334 <methodname>Zend_Ldap::search()</methodname> for a detailed description of
335 the method parameters.
341 <code>array getEntry(string|Zend_Ldap_Dn $dn, array
342 $attributes, boolean $throwOnNotFound)</code>
346 Retrieves the <acronym>LDAP</acronym> entry identified by
347 <varname>$dn</varname> with the attributes specified in
348 <varname>$attributes</varname>. if <varname>$attributes</varname> is
349 ommitted, all attributes (<methodname>array()</methodname>) are included in
350 the result. <varname>$throwOnNotFound</varname> is
351 <constant>FALSE</constant> by default, so the method will return
352 <constant>NULL</constant> if the specified entry cannot be found. If set to
353 <constant>TRUE</constant>, a <classname>Zend_Ldap_Exception</classname> will
360 <emphasis><code>void prepareLdapEntryArray(array
361 &$entry)</code></emphasis>
365 Prepare an array for the use in <acronym>LDAP</acronym> modification
366 operations. This method does not need to be called by the end-user
367 as it's implicitly called on every data modification
374 <code>Zend_Ldap add(string|Zend_Ldap_Dn $dn, array
379 Adds the entry identified by <varname>$dn</varname> with its attributes
380 <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
381 <classname>Zend_Ldap_Exception</classname> if the entry could not be
388 <code>Zend_Ldap update(string|Zend_Ldap_Dn $dn, array $entry)</code>
392 Updates the entry identified by <varname>$dn</varname> with its attributes
393 <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
394 <classname>Zend_Ldap_Exception</classname> if the entry could not be
401 <code>Zend_Ldap save(string|Zend_Ldap_Dn $dn, array $entry)</code>
405 Saves the entry identified by <varname>$dn</varname> with its attributes
406 <varname>$entry</varname> to the <acronym>LDAP</acronym> tree. Throws a
407 <classname>Zend_Ldap_Exception</classname> if the entry could not be saved.
408 This method decides by querying the <acronym>LDAP</acronym> tree if the
409 entry will be added or updated.
415 <code>Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean $recursively)</code>
419 Deletes the entry identified by <varname>$dn</varname> from the
420 <acronym>LDAP</acronym> tree. Throws a
421 <classname>Zend_Ldap_Exception</classname> if the entry could not be
422 deleted. <varname>$recursively</varname> is <constant>FALSE</constant> by
423 default. If set to <constant>TRUE</constant> the deletion will be carried
424 out recursively and will effectively delete a complete subtree. Deletion
425 will fail if <varname>$recursively</varname> is <constant>FALSE</constant>
426 and the entry <varname>$dn</varname> is not a leaf entry.
432 <code>Zend_Ldap moveToSubtree(string|Zend_Ldap_Dn $from,
433 string|Zend_Ldap_Dn $to, boolean $recursively, boolean
434 $alwaysEmulate)</code>
438 Moves the entry identified by <varname>$from</varname> to a location below
439 <varname>$to</varname> keeping its <acronym>RDN</acronym> unchanged.
440 <varname>$recursively</varname> specifies if the operation will be
441 carried out recursively (<constant>FALSE</constant> by default) so that the
442 entry <varname>$from</varname> and all its descendants will be moved.
443 Moving will fail if <varname>$recursively</varname> is
444 <constant>FALSE</constant> and the entry <varname>$from</varname> is not a
445 leaf entry. <varname>$alwaysEmulate</varname> controls whether the ext/ldap
446 function <methodname>ldap_rename()</methodname> should be used if available.
447 This can only work for leaf entries and for servers and for ext/ldap
448 supporting this function. Set to <constant>TRUE</constant> to always use an
449 emulated rename operation.
453 All move-operations are carried out by copying and then deleting the
454 corresponding entries in the <acronym>LDAP</acronym> tree. These
455 operations are not <emphasis>atomic</emphasis> so that failures
456 during the operation will result in an
457 <emphasis>inconsistent</emphasis> state on the
458 <acronym>LDAP</acronym> server. The same is true for all recursive
459 operations. They also are by no means atomic. Please keep this in
468 <code>Zend_Ldap move(string|Zend_Ldap_Dn $from,
469 string|Zend_Ldap_Dn $to, boolean $recursively, boolean
470 $alwaysEmulate)</code>
474 This is an alias for <methodname>Zend_Ldap::rename()</methodname>.
480 <code>Zend_Ldap rename(string|Zend_Ldap_Dn $from,
481 string|Zend_Ldap_Dn $to, boolean $recursively, boolean
482 $alwaysEmulate)</code>
486 Renames the entry identified by <varname>$from</varname> to
487 <varname>$to</varname>. <varname>$recursively</varname> specifies if the
488 operation will be carried out recursively (<constant>FALSE</constant> by
489 default) so that the entry <varname>$from</varname> and all its
490 descendants will be moved. Moving will fail if
491 <varname>$recursively</varname> is <constant>FALSE</constant> and the entry
492 <varname>$from</varname> is not a leaf entry.
493 <varname>$alwaysEmulate</varname> controls whether the ext/ldap function
494 <methodname>ldap_rename()</methodname> should be used if available. This can
495 only work for leaf entries and for servers and for ext/ldap supporting this
496 function. Set to <constant>TRUE</constant> to always use an emulated rename
503 <code>Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from,
504 string|Zend_Ldap_Dn $to, boolean $recursively)</code>
508 Copies the entry identified by <varname>$from</varname> to a location below
509 <varname>$to</varname> keeping its <acronym>RDN</acronym> unchanged.
510 <varname>$recursively</varname> specifies if the operation will be
511 carried out recursively (<constant>FALSE</constant> by default) so that the
512 entry <varname>$from</varname> and all its descendants will be copied.
513 Copying will fail if <varname>$recursively</varname> is
514 <constant>FALSE</constant> and the entry <varname>$from</varname> is not a
521 <code>Zend_Ldap copy(string|Zend_Ldap_Dn $from,
522 string|Zend_Ldap_Dn $to, boolean $recursively)</code>
526 Copies the entry identified by <varname>$from</varname> to
527 <varname>$to</varname>. <varname>$recursively</varname> specifies if the
528 operation will be carried out recursively (<constant>FALSE</constant> by
529 default) so that the entry <varname>$from</varname> and all its
530 descendants will be copied. Copying will fail if
531 <varname>$recursively</varname> is <constant>FALSE</constant> and the entry
532 <varname>$from</varname> is not a leaf entry.
537 <entry><code>Zend_Ldap_Node getNode(string|Zend_Ldap_Dn $dn)</code></entry>
540 Returns the entry <varname>$dn</varname> wrapped in a
541 <classname>Zend_Ldap_Node</classname>.
546 <entry><code>Zend_Ldap_Node getBaseNode()</code></entry>
549 Returns the entry for the base DN <varname>$baseDn</varname>
550 wrapped in a <classname>Zend_Ldap_Node</classname>.
555 <entry><code>Zend_Ldap_Node_RootDse getRootDse()</code></entry>
556 <entry>Returns the RootDSE for the current server.</entry>
560 <entry><code>Zend_Ldap_Node_Schema getSchema()</code></entry>
562 Returns the <acronym>LDAP</acronym> schema for the current server.
569 <sect4 id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection">
570 <title>Zend_Ldap_Collection</title>
573 <classname>Zend_Ldap_Collection</classname> implements <code>Iterator</code> to
574 allow for item traversal using <methodname>foreach()</methodname> and
575 <code>Countable</code> to be able to respond to <methodname>count()</methodname>. With
576 its protected <methodname>_createEntry()</methodname> method it provides a simple
577 extension point for developers needing custom result objects.
580 <table id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection.table">
581 <title>Zend_Ldap_Collection API</title>
586 <entry>Method</entry>
587 <entry>Description</entry>
594 <code>__construct(Zend_Ldap_Collection_Iterator_Interface
599 Constructor. The constrcutor must be provided by a
600 <classname>Zend_Ldap_Collection_Iterator_Interface</classname> which
601 does the real result iteration.
602 <classname>Zend_Ldap_Collection_Iterator_Default</classname> is the
603 default implementation for iterating ext/ldap results.
608 <entry><code>boolean close()</code></entry>
611 Closes the internal iterator. This is also called in the destructor.
616 <entry><code>array toArray()</code></entry>
617 <entry>Returns all entries as an array.</entry>
621 <entry><code>array getFirst()</code></entry>
624 Returns the first entry in the collection or
625 <constant>NULL</constant> if the collection is empty.