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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.ldap.api.reference.zend-ldap-dn">
   4     <title>Zend_Ldap_Dn</title>
   5
   6     <para>
   7         <classname>Zend_Ldap_Dn</classname> provides an object-oriented interface to
   8         manipulating <acronym>LDAP</acronym> distinguished names (DN). The parameter
   9         <varname>$caseFold</varname> that is used in several methods determines the way DN
  10         attributes are handled regarding their case. Allowed values for this paraneter are:
  11     </para>
  12
  13     <variablelist>
  14         <varlistentry>
  15             <term><constant>Zend_Ldap_Dn::ATTR_CASEFOLD_NONE</constant></term>
  16             <listitem><para>No case-folding will be done.</para></listitem>
  17         </varlistentry>
  18
  19         <varlistentry>
  20             <term><constant>Zend_Ldap_Dn::ATTR_CASEFOLD_UPPER</constant></term>
  21             <listitem><para>All attributes will be converted to upper-case.</para></listitem>
  22         </varlistentry>
  23
  24         <varlistentry>
  25             <term><constant>Zend_Ldap_Dn::ATTR_CASEFOLD_LOWER</constant></term>
  26             <listitem><para>All attributes will be converted to lower-case.</para></listitem>
  27         </varlistentry>
  28     </variablelist>
  29
  30     <para>
  31         The default case-folding is <constant>Zend_Ldap_Dn::ATTR_CASEFOLD_NONE</constant> and
  32         can be set with <methodname>Zend_Ldap_Dn::setDefaultCaseFold()</methodname>. Each instance
  33         of <classname>Zend_Ldap_Dn</classname> can have its own case-folding-setting. If the
  34         <varname>$caseFold</varname> parameter is ommitted in method-calls it defaults to the
  35         instance's case-folding setting.
  36     </para>
  37
  38     <para>
  39         The class implements <code>ArrayAccess</code> to allow indexer-access to the
  40         different parts of the DN. The <code>ArrayAccess</code>-methods proxy to
  41         <methodname>Zend_Ldap_Dn::get($offset, 1, null)</methodname> for <code>offsetGet(integer
  42         $offset)</code>, to <methodname>Zend_Ldap_Dn::set($offset, $value)</methodname> for
  43         <methodname>offsetSet()</methodname> and to
  44         <methodname>Zend_Ldap_Dn::remove($offset, 1)</methodname> for
  45         <methodname>offsetUnset()</methodname>. <methodname>offsetExists()</methodname> simply
  46         checks if the index is within the bounds.
  47     </para>
  48
  49     <table id="zend.ldap.api.reference.zend-ldap-dn.table">
  50         <title>Zend_Ldap_Dn API</title>
  51
  52         <tgroup cols="2">
  53             <thead>
  54                 <row>
  55                     <entry>Method</entry>
  56                     <entry>Description</entry>
  57                 </row>
  58             </thead>
  59
  60             <tbody>
  61                 <row>
  62                     <entry>
  63                         <emphasis><code>Zend_Ldap_Dn factory(string|array $dn,
  64                         string|null $caseFold)</code> </emphasis>
  65                     </entry>
  66
  67                     <entry>
  68                         Creates a <classname>Zend_Ldap_Dn</classname> instance from an array
  69                         or a string. The array must conform to the array structure detailed
  70                         under <methodname>Zend_Ldap_Dn::implodeDn()</methodname>.
  71                     </entry>
  72                 </row>
  73
  74                 <row>
  75                     <entry>
  76                         <emphasis><code>Zend_Ldap_Dn fromString(string $dn,
  77                         string|null $caseFold)</code> </emphasis>
  78                     </entry>
  79
  80                     <entry>
  81                         Creates a <classname>Zend_Ldap_Dn</classname> instance from a
  82                         string.
  83                     </entry>
  84                 </row>
  85
  86                 <row>
  87                     <entry>
  88                         <emphasis><code>Zend_Ldap_Dn fromArray(array $dn,
  89                         string|null $caseFold)</code> </emphasis>
  90                     </entry>
  91
  92                     <entry>
  93                         Creates a <classname>Zend_Ldap_Dn</classname> instance from an array.
  94                         The array must conform to the array structure detailed under
  95                         <methodname>Zend_Ldap_Dn::implodeDn()</methodname>.
  96                     </entry>
  97                 </row>
  98
  99                 <row>
 100                     <entry><code>array getRdn(string|null $caseFold)</code></entry>
 101
 102                     <entry>
 103                         Gets the <acronym>RDN</acronym> of the current DN. The return value is an
 104                         array with the <acronym>RDN</acronym> attribute names its keys and the
 105                         <acronym>RDN</acronym> attribute values.
 106                     </entry>
 107                 </row>
 108
 109                 <row>
 110                     <entry><code>string getRdnString(string|null $caseFold)</code></entry>
 111
 112                     <entry>
 113                         Gets the <acronym>RDN</acronym> of the current DN. The return value is a
 114                         string.
 115                     </entry>
 116                 </row>
 117
 118                 <row>
 119                     <entry><code>Zend_Ldap_Dn getParentDn(integer $levelUp)</code></entry>
 120
 121                     <entry>
 122                         Gets the DN of the current DN's ancestor
 123                         <varname>$levelUp</varname> levels up the tree. <varname>$levelUp</varname>
 124                         defaults to <code>1</code>.
 125                     </entry>
 126                 </row>
 127
 128                 <row>
 129                     <entry>
 130                         <code>array get(integer $index, integer $length, string|null
 131                         $caseFold)</code>
 132                     </entry>
 133
 134                     <entry>
 135                         Returns a slice of the current DN determined by
 136                         <varname>$index</varname> and <varname>$length</varname>.
 137                         <varname>$index</varname> starts with <code>0</code> on the DN part from the
 138                         left.
 139                     </entry>
 140                 </row>
 141
 142                 <row>
 143                     <entry><code>Zend_Ldap_Dn set(integer $index, array $value)</code></entry>
 144
 145                     <entry>
 146                         Replaces a DN part in the current DN. This operation
 147                         manipulates the current instance.
 148                     </entry>
 149                 </row>
 150
 151                 <row>
 152                     <entry><code>Zend_Ldap_Dn remove(integer $index, integer $length)</code></entry>
 153
 154                     <entry>
 155                         Removes a DN part from the current DN. This operation
 156                         manipulates the current instance. <varname>$length</varname> defaults to
 157                         <code>1</code>
 158                     </entry>
 159                 </row>
 160
 161                 <row>
 162                     <entry><code>Zend_Ldap_Dn append(array $value)</code></entry>
 163
 164                     <entry>
 165                         Appends a DN part to the current DN. This operation
 166                         manipulates the current instance.
 167                     </entry>
 168                 </row>
 169
 170                 <row>
 171                     <entry><code>Zend_Ldap_Dn prepend(array $value)</code></entry>
 172
 173                     <entry>
 174                         Prepends a DN part to the current DN. This operation
 175                         manipulates the current instance.
 176                     </entry>
 177                 </row>
 178
 179                 <row>
 180                     <entry><code>Zend_Ldap_Dn insert(integer $index, array $value)</code></entry>
 181
 182                     <entry>
 183                         Inserts a DN part after the index <varname>$index</varname> to the
 184                         current DN. This operation manipulates the current
 185                         instance.
 186                     </entry>
 187                 </row>
 188
 189                 <row>
 190                     <entry><code>void setCaseFold(string|null $caseFold)</code></entry>
 191
 192                     <entry>
 193                         Sets the case-folding option to the current DN instance. If
 194                         <varname>$caseFold</varname> is <constant>NULL</constant> the default
 195                         case-folding setting (<constant>Zend_Ldap_Dn::ATTR_CASEFOLD_NONE</constant>
 196                         by default or set via
 197                         <methodname>Zend_Ldap_Dn::setDefaultCaseFold()</methodname> will be set for
 198                         the current instance.
 199                     </entry>
 200                 </row>
 201
 202                 <row>
 203                     <entry><code>string toString(string|null $caseFold)</code></entry>
 204                     <entry>Returns DN as a string.</entry>
 205                 </row>
 206
 207                 <row>
 208                     <entry><code>array toArray(string|null $caseFold)</code></entry>
 209                     <entry>Returns DN as an array.</entry>
 210                 </row>
 211
 212                 <row>
 213                     <entry><code>string __toString()</code></entry>
 214
 215                     <entry>
 216                         Returns DN as a string - proxies to
 217                         <methodname>Zend_Ldap_Dn::toString(null)</methodname>.
 218                     </entry>
 219                 </row>
 220
 221                 <row>
 222                     <entry>
 223                         <emphasis><code>void setDefaultCaseFold(string
 224                         $caseFold)</code> </emphasis>
 225                     </entry>
 226
 227                     <entry>
 228                         Sets the default case-folding option used by all instances
 229                         on creation by default. Already existing instances are not affected
 230                         by this setting.
 231                     </entry>
 232                 </row>
 233
 234                 <row>
 235                     <entry>
 236                         <emphasis><code>array escapeValue(string|array
 237                         $values)</code> </emphasis>
 238                     </entry>
 239
 240                     <entry>Escapes a DN value according to <acronym>RFC</acronym> 2253.</entry>
 241                 </row>
 242
 243                 <row>
 244                     <entry>
 245                         <emphasis><code>array unescapeValue(string|array
 246                         $values)</code> </emphasis>
 247                     </entry>
 248
 249                     <entry>
 250                         Undoes the conversion done by
 251                         <methodname>Zend_Ldap_Dn::escapeValue()</methodname>.
 252                     </entry>
 253                 </row>
 254
 255                 <row>
 256                     <entry>
 257                         <emphasis><code>array explodeDn(string $dn, array
 258                         &amp;$keys, array &amp;$vals, string|null $caseFold)</code>
 259                         </emphasis>
 260                     </entry>
 261
 262                     <entry>
 263                         <para>
 264                             Explodes the DN <varname>$dn</varname> into an array containing
 265                             all parts of the given DN. <varname>$keys</varname> optinally receive DN
 266                             keys (e.g. CN, OU, DC, ...). <varname>$vals</varname> optionally receive
 267                             DN values. The resulting array will be of type
 268                         </para>
 269
 270                         <programlisting language="php"><![CDATA[
 271 array(
 272 array("cn" => "name1", "uid" => "user"),
 273 array("cn" => "name2"),
 274 array("dc" => "example"),
 275 array("dc" => "org")
 276 )
 277 ]]></programlisting>
 278
 279                         <para>
 280                             for a DN of <code>cn=name1+uid=user,cn=name2,dc=example,dc=org</code>.
 281                         </para>
 282                     </entry>
 283                 </row>
 284
 285                 <row>
 286                     <entry>
 287                         <emphasis><code>boolean checkDn(string $dn, array
 288                         &amp;$keys, array &amp;$vals, string|null $caseFold)</code>
 289                         </emphasis>
 290                     </entry>
 291
 292                     <entry>
 293                         Checks if a given DN <varname>$dn</varname> is malformed. If
 294                         <varname>$keys</varname> or <varname>$keys</varname> and
 295                         <varname>$vals</varname> are given, these arrays will be filled with the
 296                         appropriate DN keys and values.
 297                     </entry>
 298                 </row>
 299
 300                 <row>
 301                     <entry>
 302                         <emphasis><code>string implodeRdn(array $part, string|null
 303                         $caseFold)</code> </emphasis>
 304                     </entry>
 305
 306                     <entry>
 307                         Returns a DN part in the form
 308                         <code>$attribute=$value</code>
 309                     </entry>
 310                 </row>
 311
 312                 <row>
 313                     <entry>
 314                         <emphasis><code>string implodeDn(array $dnArray,
 315                         string|null $caseFold, string $separator)</code>
 316                         </emphasis>
 317                     </entry>
 318
 319                     <entry>
 320                         <para>
 321                             Implodes an array in the form delivered by
 322                             <methodname>Zend_Ldap_Dn::explodeDn()</methodname> to a DN string.
 323                             <varname>$separator</varname> defaults to <code>','</code> but some LDAP
 324                             servers also understand <code>';'</code>. <varname>$dnArray</varname>
 325                             must of type
 326                         </para>
 327
 328                         <programlisting language="php"><![CDATA[
 329 array(
 330 array("cn" => "name1", "uid" => "user"),
 331 array("cn" => "name2"),
 332 array("dc" => "example"),
 333 array("dc" => "org")
 334 )
 335 ]]></programlisting>
 336                     </entry>
 337                 </row>
 338
 339                 <row>
 340                     <entry>
 341                         <emphasis><code>boolean isChildOf(string|Zend_Ldap_Dn
 342                         $childDn, string|Zend_Ldap_Dn $parentDn)</code> </emphasis>
 343                     </entry>
 344
 345                     <entry>
 346                         Checks if given <varname>$childDn</varname> is beneath
 347                         <varname>$parentDn</varname> subtree.
 348                     </entry>
 349                 </row>
 350             </tbody>
 351         </tgroup>
 352     </table>
 353 </sect3>