Attributes

Reading attributes

Reading attribute values depends on the selection of those attributes at search time. You can only access attributes that where selected! You can read attribute values using either Net_LDAP_Entry's getValues() or getValue() method. getValue() will return an array where the keys are the attributes names. If you use getValues() you may pass an option:

• 'single': only the first value is returned as string

• 'all': all values including the value count are returned in an array

• 'default': in all other cases an attribute value with a single value is returned as string, if it has multiple values it is returned as an array (without value count)

// read Surename, singlevalued
$surename = $entry->getValue('sn', 'single');

// read mail adress which may be multivalued
$mail = $entry->getValue('mail', 'all');

If you want to read the distinguished name of an Entry (DN), you must use a different method: dn()

Example 51-2. Reading an entries DN $dn = $entry->dn();

Regular expressions on attributes

PEAR::Net_LDAP features the unique feature to apply a regular expression match directly against attributes, so you do not need to manually fetch all values and run the regex against them. Instead, you can use Net_LDAP_Entry's preg_match() function. The behavior of this function is the same as PHPs preg_match(), but the $matches array is slightly different. It features one dimension more, since it may match for several attribute values if the attribute is multivalued. If you pass $matches, be sure to do it via REFERENCE, because otherwise $matches remains empty. preg_match() returns true or false, depending on match.

// Look, if the user has an emailadress for 'example', if so,
// we want to display the tld:
// (be sure to pass $matches as reference!)
$matches = array();
if ( $entry->preg_match('mail', '/example\.(.+)/', &$matches) ) {
    // print every TLD found for 'example':
    foreach ($matches as $match) {
        echo $match[1];
    }
}

General information regarding attribute changing

It is important to know how attribute changing works. Modifications to an entry through the Net_LDAP_Entry-object are local only. After you have made all changes and want to transfer them to the directory server, you must call update() of the Net_LDAP_Entry object. This will return either TRUE or an Net_LDAP_Error. Another good information is, that you must select attributes at search time if you want to add/change/delete attribute values. Otherwise Net_LDAP will most likely fail silently giving you the wrong assumtion that everything was okay - Net_LDAP needs knowledge of the attributes it should work with!

Modification of attributes is also possible through Net_LDAP's modify() method. This method will call the methods described here on the Net_LDAP_Entry object given, and directly calls an update() after that, thus performing the changes directly on the server. The parameter is an complex array describing the changes to be performed. It is considered for more advanced users, because it is more compact, so please refer to the latest API documentation for more information.

Adding attributes

Adding attrbiute values to an entry is an easy task. You just need to call add()! The parameter is an array whose keys are the attribute names and values the attributes values. If only one attribute value should be added, the second level may be a string. If the attribute doesn't exist so far, it will be added, if it exists, the attributes values will be added.

// Adding several attributes:
$result = $entry->add(
    array(
        'sn'   => 'Doe',
        'gn'   => array('John'),
        'mail' => array('john@doe.org', 'j.doe@example.org')
    )
);

Changing attributes

Changing values is with the replace() method as easy as adding values. However, you have to be a little more careful. The expected parameter is an array describing the new absolute state of the named attributes. This means, if you specify a NULL value for an attribute, this attribute will get deleted! You may specify single values as string too. The keys of the array are expected to be the attributes names.

// Changing several attributes:
// 'sn' is changed to "Smith", 'gn' gets deleted and mail will
// be changed to te two new adresses
$result = $entry->replace(
    array(
        'sn'   => 'Smith',
        'gn'   => null,
        'mail' => array('smith@example.org', 'smith@example.de')
    )
);

Deleting attributes

Using the delete() method you are able to delete specific attributes values as well as delete a whole attribute. You need to specify the attribute names as array keys, the array values are the values you want to delete. If you want to delete whole attributes, specify them as single level array. Special care must be taken not to delete the whole entry which will be the case if the parameter array is omitted or set to NULL! Also, don't mix syntax modes. If you want to delete whole attributes you can't delete specific values from another attribute in the same function call.

// Delete the whole entry:
$result = $entry->delete();

// Delete the whole telephone number attribute:
$result = $entry->delete('telephoneNumber');

// Delete one specific mail attributes value:
$result = $entry->delete( array('mail' => 'j.doe@example.org') );

// Delete mail and telephone attributes as a whole:
$result = $entry->delete( array('mail', 'telephoneNumber') );

// Delete two specific mail adresses:
$result = $entry->delete( array('mail' => array('smith@example.org', 'smith@example.de')) );