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_LDAP2_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)
Also note that if you try to fetch an attribute, that is not set at the entry, an empty string will be returned.
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_LDAP2 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_LDAP2_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_LDAP2_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_LDAP2_Entry object.
This will return either TRUE or an Net_LDAP2_Error.
Another good information is, that you must select attributes at search time
if you want to add/change/delete attribute values. Otherwise Net_LDAP2 will most likely fail
silently giving you the wrong assumtion that everything was okay - Net_LDAP2 needs knowledge
of the attributes it should work with!
Modification of attributes is also possible through Net_LDAP2's modify() method. This method will call the methods described here on the Net_LDAP2_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_LDAP2 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_LDAP2_Entry::createFresh($entry->dn(), $entry->getValues());
// Now delete the old entry and add the new one:
$ldap->delete($entry);
$ldap->add($changed_entry);
?>
Schema checks
When operating on an LDAP connection, you might want to retrieve informations regarding the directory servers schema. Often this is the case to verify that your program only querys attributes that are valid for an entry or to ensure that you only try to write such attributes to the server.
To get that inforamtion, you can use the Net_LDAP2_Schema which is retrieved via the Net_LDAP2 object. It allows you to perform various querys, not only on attributes and object classes, but also on DIT content rules, for example. For often needed functionality, shorthand methods are implemented since version 2.0.10 like attributeExists(), objectClassExists(), getAssignedOCLs() and checkAttribute().
Performing basic schema checks
<?php
// Fetch the schema object for the connected directory server.
$schema = $ldap->schema();
// this may have failed since not every server allows us
// to fetch the schema without permission. Also technical
// problems may prevent us from this.
if ( Net_LDAP2::isError($schema) ) {
die('SCHEMA ERROR: '.$schema->getMessage()."\n");
}
// lets see, if an attribute is defined in the schema:
if ( $schema->attributeExists('myCoolAttribute') ) {
echo "Attribute 'myCoolAttribute' is defined in the schema!";
}
// lets see, if an object class is defined in the schema:
if ( $schema->attributeExists('myCoolOCL') ) {
echo "Object class 'myCoolOCL' is defined in the schema!";
}
// Check, if the attribute is defined in objectClasses.
// This is especially useful if you want to know if
// attributes are valid for a given set of object classes.
if ( $schema->checkAttribute('myCoolAttribute', array('person', 'myCoolOCL')) ) {
echo "Attribute 'myCoolAttribute' is defined for the given OCLs!";
}
?>