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)

Reading attributes


<?php
// 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()

Reading an entries DN


<?php
$dn = $entry->dn();
?>

Regular expressions on attributes

PEAR::Net_LDAP has 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.

Performing preg_match on attribute values


<?php
// 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 attributes


<?php
// 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 attributes


<?php
// 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.

Deleting attributes


<?php
// 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')) );
?>

Changing Objectclasses

Object classes describe the attribute set of an entry with this objectclass set. The entry stores the objectclass in a special attribute named "objectClass", and of course you may alter that attribute like any other attribute.

However, special care must be taken if changing this attribute since most directory servers impose rules on the other attributes the object class define. For example, it is usually not possible to delete an objectclass if some of the attributes the class describes are still in use by the entry. This should be not much of a problem with optional attributes, but sometimes objectclasses have mandatory attributes set. Also structural objectclasses can only be added when creating new entrys. Because of the internal architecture of Net_LDAP it is currently not possible to resolve those cases.

To add or remove objectclasses with mandatory attributes or new structural object classes, you need to delete the old entry from the directory server and add the new one with the new objectclass and attributes as fresh entry.

Changing complex objectclasses


<?php
// Let's assume that the objectclass myClass enforce the attribute "fooattr"
// Take care that you have all attributes requested, otherwise the new
// entry will not have all attributes set!
$entry->add(array(
    'objectClass'   => 'myClass',
    'fooatrr'       => 'foo',
    'someotherattr' => array('bar', 'baz')
    ));

// Calling $entry->update() now will not succeed under some circumstances!
// We construct a fresh entry object which is in fact a copy of the already
// existing entry with all changes already applied (the local copy).
// It is important, that at fetching time of $entry all attributes where selected!
// Only the selected attributes will get copied.
$changed_entry = Net_LDAP_Entry::createFresh($entry->dn(), $entry->getValues());

// Now delete the old entry and add the new one:
$ldap->delete($entry);
$ldap->add($changed_entry);
?>

Attributes