documentation/manual/en/module_specs/Zend_Ldap-API-Ldap.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.ldap.api.reference.zend-ldap">
   4     <title>Zend_Ldap</title>
   5
   6     <para>
   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.
  10     </para>
  11
  12     <table id="zend.ldap.api.reference.zend-ldap.table">
  13         <title>Zend_Ldap API</title>
  14
  15         <tgroup cols="2">
  16             <thead>
  17                 <row>
  18                     <entry>Method</entry>
  19                     <entry>Description</entry>
  20                 </row>
  21             </thead>
  22
  23             <tbody>
  24                 <row>
  25                     <entry><code>string filterEscape(string $str)</code></entry>
  26
  27                     <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>
  31                         instead.
  32                     </entry>
  33                 </row>
  34
  35                 <row>
  36                     <entry>
  37                         <code>boolean explodeDn($dn, array &amp;$keys = null, array &amp;$vals =
  38                             null)</code>
  39                     </entry>
  40
  41                     <entry>
  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.
  48                     </entry>
  49                 </row>
  50
  51                 <row>
  52                     <entry><methodname>__construct($options)</methodname></entry>
  53
  54                     <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
  60                         specified in <link
  61                             linkend="zend.ldap.api.configuration.table">Zend_Ldap
  62                             Options</link>
  63                     </entry>
  64                 </row>
  65
  66                 <row>
  67                     <entry><code>resource getResource()</code></entry>
  68
  69                     <entry>
  70                         Returns the raw <acronym>LDAP</acronym> extension (ext/ldap) resource.
  71                     </entry>
  72                 </row>
  73
  74                 <row>
  75                     <entry><code>integer getLastErrorCode()</code></entry>
  76
  77                     <entry>
  78                         Returns the <acronym>LDAP</acronym> error number of the last
  79                         <acronym>LDAP</acronym> command.
  80                     </entry>
  81                 </row>
  82
  83                 <row>
  84                     <entry>
  85                         <code>string getLastError(integer &amp;$errorCode, array
  86                             &amp;$errorMessages)</code>
  87                     </entry>
  88
  89                     <entry>
  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.
  97                     </entry>
  98                 </row>
  99
 100                 <row>
 101                     <entry><code>Zend_Ldap setOptions($options)</code></entry>
 102
 103                     <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
 107                         <link
 108                             linkend="zend.ldap.api.configuration.table">Zend_Ldap Options</link>
 109                     </entry>
 110                 </row>
 111
 112                 <row>
 113                     <entry><code>array getOptions()</code></entry>
 114                     <entry>Returns the current connection and binding parameters.</entry>
 115                 </row>
 116
 117                 <row>
 118                     <entry><code>string getBaseDn()</code></entry>
 119
 120                     <entry>
 121                         Returns the base DN this <acronym>LDAP</acronym> connection is bound
 122                         to.
 123                     </entry>
 124                 </row>
 125
 126                 <row>
 127                     <entry>
 128                         <code>string getCanonicalAccountName(string $acctname, integer $form)</code>
 129                     </entry>
 130
 131                     <entry>
 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.
 138                     </entry>
 139                 </row>
 140
 141                 <row>
 142                     <entry><code>Zend_Ldap disconnect()</code></entry>
 143
 144                     <entry>
 145                         Disconnects the Zend_Ldap instance from the <acronym>LDAP</acronym>
 146                         server.
 147                     </entry>
 148                 </row>
 149
 150                 <row>
 151                     <entry>
 152                         <code>Zend_Ldap connect(string $host, integer $port, boolean $useSsl,
 153                             boolean $useStartTls)</code>
 154                     </entry>
 155
 156                     <entry>
 157                         Connects the Zend_Ldap instance to the given <acronym>LDAP</acronym> server.
 158                         All parameters are optional and will be taken from the
 159                         <acronym>LDAP</acronym> connection and binding parameters passed to the
 160                         instance via the construtor or via
 161                         <methodname>Zend_Ldap::setOptions()</methodname> when set to
 162                         <constant>NULL</constant>.
 163                     </entry>
 164                 </row>
 165
 166                 <row>
 167                     <entry>
 168                         <code>Zend_Ldap bind(string $username, string $password)</code>
 169                     </entry>
 170
 171                     <entry>
 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.
 182                     </entry>
 183                 </row>
 184
 185                 <row>
 186                     <entry>
 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>
 190                     </entry>
 191
 192                     <entry>
 193                         Searches the <acronym>LDAP</acronym> tree with the given
 194                         <varname>$filter</varname> and the given search parameters.
 195
 196                         <variablelist>
 197                             <varlistentry>
 198                                 <term><code>string|Zend_Ldap_Filter_Abstract $filter</code></term>
 199
 200                                 <listitem>
 201                                     <para>
 202                                         The filter string to be used in the search, e.g.
 203                                         <code>(objectClass=posixAccount)</code>.
 204                                     </para>
 205                                 </listitem>
 206                             </varlistentry>
 207
 208                             <varlistentry>
 209                                 <term><code>string|Zend_Ldap_Dn $basedn</code></term>
 210
 211                                 <listitem>
 212                                     <para>
 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.
 216                                     </para>
 217                                 </listitem>
 218                             </varlistentry>
 219
 220                             <varlistentry>
 221                                 <term><code>integer $scope</code></term>
 222
 223                                 <listitem>
 224                                     <para>
 225                                         The search scope.
 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
 234                                         default value is
 235                                         <constant>Zend_Ldap::SEARCH_SCOPE_SUB</constant>.
 236                                     </para>
 237                                 </listitem>
 238                             </varlistentry>
 239
 240                             <varlistentry>
 241                                 <term><code>array $attributes</code></term>
 242
 243                                 <listitem>
 244                                     <para>
 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.
 254                                     </para>
 255                                 </listitem>
 256                             </varlistentry>
 257
 258                             <varlistentry>
 259                                 <term><code>string $sort</code></term>
 260
 261                                 <listitem>
 262                                     <para>
 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>.
 267                                     </para>
 268                                 </listitem>
 269                             </varlistentry>
 270
 271                             <varlistentry>
 272                                 <term><code>string $collectionClass</code></term>
 273
 274                                 <listitem>
 275                                     <para>
 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
 281                                         passed a
 282                                         <classname>Zend_Ldap_Collection_Iterator_Default</classname>
 283                                         on instantiation.
 284                                     </para>
 285                                 </listitem>
 286                             </varlistentry>
 287                         </variablelist>
 288                     </entry>
 289                 </row>
 290
 291                 <row>
 292                     <entry>
 293                         <code>integer count(string|Zend_Ldap_Filter_Abstract
 294                         $filter, string|Zend_Ldap_Dn $basedn, integer
 295                         $scope)</code>
 296                     </entry>
 297
 298                     <entry>
 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.
 302                     </entry>
 303                 </row>
 304
 305                 <row>
 306                     <entry><code>integer countChildren(string|Zend_Ldap_Dn $dn)</code></entry>
 307
 308                     <entry>
 309                         Counts the direct descendants (children) of the entry
 310                         identified by the given <varname>$dn</varname>.
 311                     </entry>
 312                 </row>
 313
 314                 <row>
 315                     <entry><code>boolean exists(string|Zend_Ldap_Dn $dn)</code></entry>
 316
 317                     <entry>
 318                         Checks whether the entry identified by the given
 319                         <varname>$dn</varname> exists.
 320                     </entry>
 321                 </row>
 322
 323                 <row>
 324                     <entry>
 325                         <code>array searchEntries(string|Zend_Ldap_Filter_Abstract
 326                         $filter, string|Zend_Ldap_Dn $basedn, integer $scope, array
 327                         $attributes, string $sort)</code>
 328                     </entry>
 329
 330                     <entry>
 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.
 336                     </entry>
 337                 </row>
 338
 339                 <row>
 340                     <entry>
 341                         <code>array getEntry(string|Zend_Ldap_Dn $dn, array
 342                         $attributes, boolean $throwOnNotFound)</code>
 343                     </entry>
 344
 345                     <entry>
 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
 354                         be thrown instead.
 355                     </entry>
 356                 </row>
 357
 358                 <row>
 359                     <entry>
 360                         <emphasis><code>void prepareLdapEntryArray(array
 361                             &amp;$entry)</code></emphasis>
 362                     </entry>
 363
 364                     <entry>
 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
 368                         method.
 369                     </entry>
 370                 </row>
 371
 372                 <row>
 373                     <entry>
 374                         <code>Zend_Ldap add(string|Zend_Ldap_Dn $dn, array
 375                         $entry)</code>
 376                     </entry>
 377
 378                     <entry>
 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
 382                         added.
 383                     </entry>
 384                 </row>
 385
 386                 <row>
 387                     <entry>
 388                         <code>Zend_Ldap update(string|Zend_Ldap_Dn $dn, array $entry)</code>
 389                     </entry>
 390
 391                     <entry>
 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
 395                         modified.
 396                     </entry>
 397                 </row>
 398
 399                 <row>
 400                     <entry>
 401                         <code>Zend_Ldap save(string|Zend_Ldap_Dn $dn, array $entry)</code>
 402                     </entry>
 403
 404                     <entry>
 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.
 410                     </entry>
 411                 </row>
 412
 413                 <row>
 414                     <entry>
 415                         <code>Zend_Ldap delete(string|Zend_Ldap_Dn $dn, boolean $recursively)</code>
 416                     </entry>
 417
 418                     <entry>
 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.
 427                     </entry>
 428                 </row>
 429
 430                 <row>
 431                     <entry>
 432                         <code>Zend_Ldap moveToSubtree(string|Zend_Ldap_Dn $from,
 433                         string|Zend_Ldap_Dn $to, boolean $recursively, boolean
 434                         $alwaysEmulate)</code>
 435                     </entry>
 436
 437                     <entry>
 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.
 450
 451                         <note>
 452                             <para>
 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
 460                                 mind.
 461                             </para>
 462                         </note>
 463                     </entry>
 464                 </row>
 465
 466                 <row>
 467                     <entry>
 468                         <code>Zend_Ldap move(string|Zend_Ldap_Dn $from,
 469                         string|Zend_Ldap_Dn $to, boolean $recursively, boolean
 470                         $alwaysEmulate)</code>
 471                     </entry>
 472
 473                     <entry>
 474                         This is an alias for <methodname>Zend_Ldap::rename()</methodname>.
 475                     </entry>
 476                 </row>
 477
 478                 <row>
 479                     <entry>
 480                         <code>Zend_Ldap rename(string|Zend_Ldap_Dn $from,
 481                         string|Zend_Ldap_Dn $to, boolean $recursively, boolean
 482                         $alwaysEmulate)</code>
 483                     </entry>
 484
 485                     <entry>
 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
 497                         operation.
 498                     </entry>
 499                 </row>
 500
 501                 <row>
 502                     <entry>
 503                         <code>Zend_Ldap copyToSubtree(string|Zend_Ldap_Dn $from,
 504                         string|Zend_Ldap_Dn $to, boolean $recursively)</code>
 505                     </entry>
 506
 507                     <entry>
 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
 515                         leaf entry.
 516                     </entry>
 517                 </row>
 518
 519                 <row>
 520                     <entry>
 521                         <code>Zend_Ldap copy(string|Zend_Ldap_Dn $from,
 522                         string|Zend_Ldap_Dn $to, boolean $recursively)</code>
 523                     </entry>
 524
 525                     <entry>
 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.
 533                     </entry>
 534                 </row>
 535
 536                 <row>
 537                     <entry><code>Zend_Ldap_Node getNode(string|Zend_Ldap_Dn $dn)</code></entry>
 538
 539                     <entry>
 540                         Returns the entry <varname>$dn</varname> wrapped in a
 541                         <classname>Zend_Ldap_Node</classname>.
 542                     </entry>
 543                 </row>
 544
 545                 <row>
 546                     <entry><code>Zend_Ldap_Node getBaseNode()</code></entry>
 547
 548                     <entry>
 549                         Returns the entry for the base DN <varname>$baseDn</varname>
 550                         wrapped in a <classname>Zend_Ldap_Node</classname>.
 551                     </entry>
 552                 </row>
 553
 554                 <row>
 555                     <entry><code>Zend_Ldap_Node_RootDse getRootDse()</code></entry>
 556                     <entry>Returns the RootDSE for the current server.</entry>
 557                 </row>
 558
 559                 <row>
 560                     <entry><code>Zend_Ldap_Node_Schema getSchema()</code></entry>
 561                     <entry>
 562                         Returns the <acronym>LDAP</acronym> schema for the current server.
 563                     </entry>
 564                 </row>
 565             </tbody>
 566         </tgroup>
 567     </table>
 568
 569     <sect4 id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection">
 570         <title>Zend_Ldap_Collection</title>
 571
 572         <para>
 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.
 578         </para>
 579
 580         <table id="zend.ldap.api.reference.zend-ldap.zend-ldap-collection.table">
 581             <title>Zend_Ldap_Collection API</title>
 582
 583             <tgroup cols="2">
 584                 <thead>
 585                     <row>
 586                         <entry>Method</entry>
 587                         <entry>Description</entry>
 588                     </row>
 589                 </thead>
 590
 591                 <tbody>
 592                     <row>
 593                         <entry>
 594                             <code>__construct(Zend_Ldap_Collection_Iterator_Interface
 595                             $iterator)</code>
 596                         </entry>
 597
 598                         <entry>
 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.
 604                         </entry>
 605                     </row>
 606
 607                     <row>
 608                         <entry><code>boolean close()</code></entry>
 609
 610                         <entry>
 611                             Closes the internal iterator. This is also called in the destructor.
 612                         </entry>
 613                     </row>
 614
 615                     <row>
 616                         <entry><code>array toArray()</code></entry>
 617                         <entry>Returns all entries as an array.</entry>
 618                     </row>
 619
 620                     <row>
 621                         <entry><code>array getFirst()</code></entry>
 622
 623                         <entry>
 624                             Returns the first entry in the collection or
 625                             <constant>NULL</constant> if the collection is empty.
 626                         </entry>
 627                     </row>
 628                 </tbody>
 629             </tgroup>
 630         </table>
 631     </sect4>
 632 </sect3>