Home » Networking » Net_LDAP » Manual

Introduction

Introduction – What Net_LDAP is and general information

Welcome to Net_LDAP!

Net_LDAP is a clone of Perls Net::LDAP package. PEAR Net_LDAP for PHP does, besides some own features, provide most of Perl Net::LDAP methods. Net_LDAP allows you to query and manipulate the data stored in directory servers using PHP in an object-oriented way. A directory server is a database server providing a hierarchical database and is usually queried using the LDAP protocol.

Classes of Net_LDAP

The following table gives you a short overview which classes are available in Net_LDAP and what they can be used for. Their relations will be explained too.

Error handling

Error handling – How handling errors works in Net_LDAP

Error handling

Nearly all of Net_LDAPs methods return a Net_LDAP_Error object if something went wrong. You always should check for errors after you performed an action to be sure that your application doesn't do things you don't want it to do.

Handling errors is an easy task, you just have to test the return value as shown below. If an error occured, you can halt the script for example. In other cases, you may just log the error, but what exactly happens depends on your specific situation, of course.

You can use the getMessage() method of the error object to retrieve the error message explaining the problem and getCode() to get the error code which is usually the LDAP-Error code (see Table below) and may be used for automated reaction on errors.

Dealing with errors

<?php
// Perform an arbitrary action:
$result = $ldap->search($searchbase, $filter, $options);

// Check, if an error occured and do something.
// Here we use die() to show the message of the error.
if (PEAR::isError($result)) {
    die($result->getMessage());
}
?>

Configuration and connecting

Configuration and connecting – How to configure Net_LDAP and connect to an LDAP server

Connecting to an LDAP server

To connect to an LDAP server, you should use Net_LDAP's static connect() method. It takes one parameter, an array full of configuration options, and either returns a Net_LDAP object if connecting works, or a Net_LDAP_Error object in case of a failure.

The following table lists all configuration options. If the default value for an option fits your needs, you don't need add it to your configuration array.

Connecting to an LDAP server

<?php
// Inclusion of the Net_LDAP package:
require_once 'Net/LDAP.php';

// The configuration array:
$config = array (
    'binddn'    => 'cn=admin,ou=users,dc=example,dc=org',
    'bindpw'    => 'password',
    'basedn'    => 'dc=example,dc=org',
    'host'      => 'ldap.example.org'
);

// Connecting using the configuration:
$ldap = Net_LDAP::connect($config);

// Testing for connection error
if (PEAR::isError($ldap)) {
    die('Could not connect to LDAP-server: '.$ldap->getMessage());
}
?>

Search

Search – Searching entries

A short note on DNs

It may be possible that restricted characters (",", "+", """, "\", "<", ">", ";", "#", "=", space or a hexpair) are used in attributes or values inside the DN. You should have a look to the APIdoc of Net_LDAP2_Util::escape_dn_value(), Net_LDAP2_Util::unescape_dn_value(), Net_LDAP2_Util::ldap_explode_dn() and Net_LDAP2_Util::canonical_dn(). These functions can be used to safely handle DNs.

Searching some entries

After connecting to the server, you can use Net_LDAP's search() method to search the directory. The method takes three parameters:

• $base is the base search DN. If kept null, the default base DN configured when connecting is used.
• $filter is the query filter that determines which results are returned. It is either a string (experts use only) or better a Net_LDAP_Filter-object. Net_LDAP_Filter automatically deals with LDAP-Filter escaping issues. LDAP filters are extensively explained at the chapter LDAP filters.
• $params is an array of configuration options for the current query.

  Possible configuration parameters

  Name	Description	Default
  scope	The scope used for searching: base - Just one entry sub - The whole tree one - Immediately below $base	sub
  sizelimit	Number of entries returned at maximum	0 (no limit)
  timelimit	Seconds to spent for searching	0 (no limit)
  attrsonly	If true, only attribute names are returned	false
  attributes	Array of attribute names, which the entry should contain. It is good practice to limit this to just the ones you need.	array() (all attributes)

The search() method will return either a Net_LDAP_Search object or a Net_LDAP_Error. You can use the Net_LDAP_Search-object to trigger further actions like counting how many entries where found or to retrieve the found entries.

Making a search query

<?php
// Building a very basic filter
// we want to find all Entries whose surnames start with "Joe":
$filter = Net_LDAP_Filter::create('sn', 'begins',  'Joe');

// We define a custom searchbase here. If you pass NULL, the basedn provided
// in the Net_LDAP configuration will be used. This is often not what you want.
$searchbase = 'ou=addressbook,dc=example,dc=org';

// Some options:
// We search all subtrees beneath 'ou=addressbook,dc=example,dc=org'
// and we select the attribute 'sn'. It is a good practice to limit the
// requested attributes to only those you actually want to use later.
// However, note that it is faster to select unneeded attributes than
// refetching an entry later to just get those attributes.
$options = array(
    'scope' => 'sub',
    'attributes' => array('sn')
);

// Perform the search!
$search = $ldap->search($searchbase, $filter, $options);

// Test for search errors:
if (PEAR::isError($search)) {
    die($search->getMessage() . "\n");
}

// Say how many entries we have found:
echo "Found " . $search->count() . " entries!";
?>

Fetching entries

Fetching entries – Retrieving entries directly or from a searchresult

Retrieving entries directly

You can retrieve directory entries in several ways, either directly or from a performed search request. If you want to fetch an entry directly, you need to know its absolute distinguished name (DN). To directly fetch an known entry from the directory server, you use Net_LDAP's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP_Entry object if fetching worked, or a Net_LDAP_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP's dnExists() which takes the DN to test and returns either true or false.

Fetching an entry directly

<?php
// Defining the DN we want to fetch;
// we want to select the given- and the surname
$dn = 'cn=admin,o=example,dc=org';
$entry = $ldap->getEntry($dn, array('gn', 'sn'));

// Error checking is important!
if (Net_LDAP::isError($entry)) {
    die('Could not fetch entry: '.$entry->getMessage());
}
?>

Retrieving entries from a searchresult

The second way to retrieve entries is from a searchresult. As described in chapter "Search", you access the entries of a search result through the Net_LDAP_Search-object resulting from Net_LDAP's search() method. Each of the following methods return a Net_LDAP_Error-object if something goes wrong, so remember to test for errors! You have several ways to read the entries:

To directly fetch an known entry from the directory server, you use Net_LDAP's getEntry() method. It takes two parameters: The DN of the entry and the attributes you want to read from the entry. It returns a Net_LDAP_Entry object if fetching worked, or a Net_LDAP_Error object in case of a failure.

You may also check if the entry exists in the server before you fetch it. This can be achieved by Net_LDAP's dnExists() which takes the DN to test and returns either true or false.

Fetching all entries from searchresult

<?php
// return all entries:
$entry = $search->entries();
?>

Fetching all entries from searchresult: sorted

<?php
// return sorted by first 'sn' then 'gn', but descending:
$entry = $search->sorted(array('sn', 'gn'), SORT_DESC);
?>

Fetching entries one by one inside a while loop

<?php
// return entries one by one:
while ( $entry = $search->shiftEntry() ) {
    // do something, like printing the DN of the entry;
    // in a real case, dont forget to test for errors!
    echo "ENTRY: " . $entry->dn();
}
?>

Attributes

Attributes – Reading/adding/changing/deleting attributes from entries

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);
?>

Managing entries

Managing entries – Adding/renaming/moving/deleting entries

Adding (fresh or old) entries to the directory

Adding new entries is performed in two ways. First, you need to establish a fresh Net_LDAP_Entry object. After that, you can add that entry like you would add already-existent entries using Net_LDAP's add() method.

Adding a fresh entry

<?php
// Build a new fresh entry:
$dn         = 'cn=new-admin,o=example,dc=org';
$attributes = array(
    'cn'              => 'new-admin',
    'mail'            => array('new-admin@exaple.org', 'n.admin@example.de'),
    'telephoneNumber' => '1234567890'
);
$entry = Net_LDAP_Entry::createFresh($dn, $attributes);

// Add the entry to the directory:
$ldap->add($entry);
?>

Renaming or moving entries

Renaming and/or moving an entry is an operation on the DN of an entry. Moving an entry means, to rename a DN in such a way, that the entry becomes a new base-DN. You can rename or move an entry, if you call the dn() method of the entry you want to relocate. Alternatively, you may call Net_LDAP's move() method that also ca handle only DNs. Remember that you must call the entires update() method to carry out the move/rename. Net_LDAP's move() will move the entry immediately. If you use an entryobject togehter with Net_LDAP's move(), you are able to perform cross directory moves.

Moving an entry using Net_LDAP_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$entry->dn($newdn);
?>

Moving an entry using Net_LDAP and Net_LDAP_Entry

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap->getEntry($dn);

$ldap->move($entry, $newdn);
?>

Renaming an entry using Net_LDAP and DNs

<?php
// Defining the DN we want to fetch;
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin2,o=new-example,dc=org';

$ldap->move($dn, $newdn);
?>

Performing a cross directory move

<?php
// $ldap_src is the source ldap and $ldap_tgt the target
$dn    = 'cn=admin,o=example,dc=org';
$newdn = 'cn=admin,o=new-example,dc=org';
$entry = $ldap_src->getEntry($dn);

$ldap_src->move($entry, $newdn, $ldap_tgt);
?>

Deleting entries

Deleting entries is performed using Net_LDAP's delete() method. Just pass the Net_LDAP_Entry object or the DN of the entry you want to delete. In the case that the DN contains subentrys, you need to pass TRUE as second parameter which will make delete() delete recursive.

A second way exist: You may simply call delete() from the Net_LDAP_Entry you want to delete. Don't forget that you must call update() to carry out the delete in this case.

Deleting an entry

<?php
$dn  = 'cn=new-admin,o=example,dc=org';
$ldap->delete($dn);
?>

Deleting an entry using a Net_LDAP_Entry object

<?php
$entry->delete();
$entry->update();
?>

LDAP filters

LDAP filters – Introduction to and usage of LDAP filters

What are LDAP filters?

LDAP filters are defined in RFC 2254 and can be compared to the WHERE clause in SQL select statements - they filter the data returned from some search request - in this case the entries returned from the directory server. With Net_LDAP, you may use plain strings as filters, or preferably, the Net_LDAP_Filter class which mostly releases you of the burden to escape yourself and to remember all the various special characters needed for constructing and combining filters.

Where and how to use filters is described in chapter Search.

Some LDIF filter basics

Although you should preferably use the Net_LDAP_Filter class to construct your LDAP filters, some theory may be interesting and helpful in understanding how to construct LDAP filters and what they are capable of.

Basic LDAP filters are composed of an "[attribute][operator][value]" pair enclosed by round brackets. There are several comparison operators available: "=" (equal), ">" (greater), "<" (less), ">=" (greater or equal), "<=" (less or equal) and "=~" (phonetical similar). The exact match behavior is defined by the attribute syntax of the attribute to which the filter should apply.

Some basic string filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = '(givenName=Benedikt)';

// Filter entries which have an employeenumber higher or equal than 1424:
$filter = '(employeeNumber>=1424)';

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

The value part of the basic filter construct could also include a special character: "*". The star acts as placeholder for none, one or several characters at that position. "V*lue" would therefore match against "Value", "Vlue", "VaaAaAalue" and so on. There are some special named combinations using the star, but they work exactly the same way:

Combining string filters

Basic filters can be combined using the three logical operators "&" (and), "|" (or) and "!" (not). Note, that the smallest filter component, the basic filter enclosed in round brackets, remains isolated: instead of just adding another "[attribute][operator][value]" pair into the brackets, a new bracket level is introduced that contains all filter components that should be combined. Note also, that the logical operator does stand in front of all filter components, not between them as common in programming languages.

Combining string filters

<?php
// Search all 'Benedikt's with phone number 1234567890
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890))';
    
    // Search the same, but exclude person "Benedikt Foobar"
    // Note that the "not" is a logical operator and thus needs its own
    // surrounding bracket. This explains nicely, that each bracket level
    // is evaluated independently from surrounding brackets.
    $filter = '(&(givenName=Benedikt)(telephoneNumber=1234567890)(!(sureName=Foobar)))';
?>

The Net_LDAP_Filter class

As you will read below, there are some special characters inside the LDAP filter definition and thus must be escaped. These are mainly the special characters used directly by the filter syntax like braces and the logical operators. Despite those, there are some other cases which need special threatment. Nearly all of this cases are hidden through the Net_LDAP_Filter class so you should only consider using string filters if you need to or you know what you are doing. If you need a filter string, you may also use Net_LDAP_Filters toString() function after building the filter.

The filter class has two different usage models: one for constructing basic filters and another to combine them logically. This has to do with the syntax of LDAP filters you may read below.

Creating filters

For creating basic filter components, you need to use the create() factory method. There, you combine three items: an attribute to filter for, a matching rule for comparison and a value that is beeing compared with the servers entries. The given value is automatically escaped, so you need take care if you want to use the star placeholder. In this case, you need to pass FALSE as fourth parameter to create() which causes value to be threaten as-is. This of course also means, that you need to escape the parts of the value that may contain restricted characters yourself using Net_LDAP_Util::escape_filter_value(). To learn what characters are restricted, refer to RFC 2254 or the documentation of Net_LDAP_Util::escape_filter_value(); otherwise its safe to always escape.

The matching rules partly follow the basic filter matching rules described above, but are enhanced to make your life easier:

Creating LDAP filters

<?php
// Filter entries whose first name is 'Benedikt':
$filter = Net_LDAP_Filter::create('givenName', 'equals', 'Benedikt');

// Filter entries whose first name starts with 'Steph':
$filter = Net_LDAP_Filter::create('givenName', 'begins', 'Steph');

// Filter entries containing 'Lone*'; matching the star character.
// The automatic escaping of $value will conveniently escape the star for us.
$filter = Net_LDAP_Filter::create('givenName', 'contains', 'Lone*');

// Filter entries containing 'Foo[something]Bar'; not matching the star character.
// For this to work, we need to disable automatic escaping of $value by passing
// false as fourth parameter. This however implies, that we take care of
// proper escaping, which is showed in the example.
$escaped_values = Net_LDAP_Util::escape_filter_value(array('Foo', 'Bar'));
$foo =& $escaped_values[0];
$bar =& $escaped_values[1];
$filter = Net_LDAP_Filter::create('givenName', 'contains', "$foo*$bar", false);

// Filter entries whose first name sounds similar to "Stephane"
// This should also find "Stephen" and "Stefan" (depending on implementation)
$filter = '(givenName=~Stephane)';
?>

Combining filters

Although the filters can be used stand alone, they can be combined to match sophisticated search requiremets. This is done by using the combine() to combine several present Net_LDAP_Filter objects using a logical operator. The execption is the not operator since it only allows one filter object to be negated.

Combining LDAP filters

<?php
// Create some test filters
$filter_benedikt = Net_LDAP_Filter::create('givenName', 'equals', 'Benedikt');
$filter_steph    = Net_LDAP_Filter::create('givenName', 'begins', 'Steph');
$filter_foobar   = Net_LDAP_Filter::create('sureName', 'equals', 'Foobar');
$filter_height   = Net_LDAP_Filter::create('personHeight', 'greater', '175');

// Negate 'foobar' filter.
// This filters every entry whose sure name is not 'Foobar'
$filter_not_foobar = Net_LDAP_Filter::combine('not', $filter_foobar);

// Build a 'and' combination to be able to search for people whose
// first names start with 'Steph' and who are are taller than 175
// except those whose surname is 'Foobar'
$filter_stephs_tall = Net_LDAP_Filter::combine('and',
    array($filter_steph, $filter_height, $filter_not_foobar));

// In any case, add every person whose first name is
// 'Benedikt' to the search result.
$filter_add_benedikt = Net_LDAP_Filter::combine('or', array($filter_benedikt, $filter_stephs_tall));
?>

Advanced features

You may need some advanced functionality if you have to deal with string representation of filters.

LDIF files

LDIF files – Converting between Net_LDAP_Entries and LDIF files

Avaible since

LDIF support was added to Net_LDAP in release 1.1.0a1.

What are LDIF files?

LDIF files are in detail described at RFC 2849. Shortly, they contain directory data in an plain text, human readable kind, much like a SQL file does. However, unlike SQL files LDIF files are mostly data based, not action based. There are two different LDIF file contents, which can be mixed freely - content and change files. The first and most often used one is the LDIF content file:

Example LDIF content file

#
# This is a content LDIF file.
# It contains one single entry featuring several
# attributes and one comment (this one).
# attr1, attr4 and cn are single valued, the others are
# multivalued. objectclass is a special case, LDAP servers
# will interpret this operational attribute to define the
# classes the object will belong to and thus, which attributes
# it may contain. the OCL-attribute is usually multivalued.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
attr2: 1234
attr2: baz
attr3: foo
attr3: bar
attr4: brrrzztt
cn: test1

LDIF files could describe not only the data an entry contains, but also various changes to the entry itself. If such an LDIF file would then be given to a LDAP server, he would interpret those changes instead just importing the data. Note in the example below, that even though LDIF content and LDIF change files could be mixed freely, this is not true for individual entries: a specific entry may be either describing content or changes, but not both.

Example LDIF change file

#
# This is a content+change LDIF file.
# It does contain the (shortened) entry from the example above to show
# that LDIF files can contain multiple entry modes.
# The second entry is a change entry. In this case, some
# operations will be done on the entries attributes.
#
version: 1
dn: cn=test1,ou=example,dc=cno
objectclass: someobjectclass
attr1: 12345
cn: test1

# Delete attr1, replace values of attr2 and add new attribute attr42
# The attribute "changetype" is special: it says, what to do with
# this entries dataset. It could also be "delete" or "add" to delete
# a whole entry or to add a completely fresh one. "modrdn" will
# move the entry to a new location once the LDIF file is imported.
dn: cn=test2,ou=example,dc=cno
changetype: modify
delete: attr1
-
replace: attr2
attr2: 123456_newtest
-
add: attr42
attr42: the answer

Error handling when using Net_LDAP_LDIF

Before we can start using Net_LDAP_LDIF we must say some short words about how error handling works. Net_LDAP_LDIF was designed to have mostly the same API as the original PERL Net::LDAP::LDIF has. Because of this, the methods of Net_LDAP_LDIF do not return a Net_LDAP_Error object. You must use the error() method that will return a Net_LDAP_Error object in case of failure or true in case everything was ok. In LDIF reading mode, you can additionally use error_lines() to get knowledge about where in the input file the error occured.

Construction and options

Regardless if you want to read or write a LDIF file, you always have to use the constructor of Net_LDAP_LDIF to initialize your access to the LDIF file. You need to pass at least one parameter to Net_LDAP_LDIF(): the path of the file that should be read or written. You may pass the open mode as second parameter. The possible file open modes are "r" (read), "w" (write, clears the file first) and "a" (append to the end). In case you omit the open mode, read mode is assumed. The third optional parameter is an associative array containing one or several of the following options:

For advanced users: instead of passing a file path, you also may pass an already initialized file handle. In this case, the mode parameter will be ignored. You may use this, if you want to mix LDIF content and LDIF change mode by using two Net_LDAP_LDIF instances to write to the same filehandle, but it could be very useful in other cases too. To initialize the second instance of Net_LDAP_LDIF, you can use handle() to get the filehandle from the first instance.

Reading a LDIF file into Net_LDAP_Entry-objects

One of the two modes how Net_LDAP_LDIF can be used is to read a LDIF file and parse its contents into an array of Net_LDAP_Entry objects. This is done using the read_entry()-method which will return the next entry. If you want to fetch all entries, you use the eof() to detect the end of the input file:

Parsing a LDIF file into Net_LDAP_Entry objects

<?php
// open some LDIF file for reading
$ldif = new Net_LDAP_LDIF('somefile.ldif', 'r');
if ($ldif->error()) {
    $error_o = $ldif->error(); // get Net_LDAP_Error object on error
            die('ERROR: '.$error_o->getMessage());
}

// parse the entries of the LDIF file into objects
 do {
    $entry = $ldif->read_entry();
    if ($ldif->error()) {
        // in case of error, print error.
        // here we use the shorthand parameter, so error()
        // returns a string instead of a Net_LDAP_Object
        die('ERROR AT INPUT LINE '.$ldif->error_lines().': '.$ldif->error(true));
    } else {
        // No error: do something with the entry
        // Here we just print the entries DN
        echo 'sucessfully parsed '.$entry->dn();
    }
} while (!$ldif->eof());

// We should call done() once we are finished
$ldif->done();
?>

Writing Net_LDAP_Entry objects to a LDIF content file

Writing an LDIF file is very easy too. Just pass the entries you want to have written to the write_entry()-method. Beware, that if you have opened the file in "w" write mode this will clear any previous data of that file. Use "a" (append) if you just want add data.

Writing entries

<?php
// Assume we have some valid Net_LDAP_Entry objects inside $entries
        // $entries = array( ... );

        // open some file for writing
        $ldif = new Net_LDAP_LDIF('somewritefile.ldif', 'w');
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());
?>

Writing Net_LDAP_Entry objects to a LDIF change file

The process of writing changes is exactly the same like writing entry contents. However there are two differences: Firstly you need to pass the "changes" option and secondly, the entries you want to write need changes. Entries not containing changes will silently be ignored since there is nothing to write.

Writing entry changes

<?php
// cast some test data and three entries
        $testattrs = array(
                'attr1' => '1234',
                'attr2' => 'foo',
                'attr3' => array('bar', 'baz')
            );
        $entries = array(
                Net_LDAP_Entry::createFresh('cn=foo,dc=example,dc=cno',
                    array_merge(array('cn' => 'foo'), $testattrs)),
                Net_LDAP_Entry::createFresh('cn=bar,dc=example,dc=cno',
                    array_merge(array('cn' => 'bar'), $testattrs)),
                Net_LDAP_Entry::createFresh('cn=baz,dc=example,dc=cno',
                    array_merge(array('cn' => 'baz'), $testattrs))
            );

        // make some changes to the first and the last entry
        $entries[0]->add(array('someattr' => 'added'));
        $entries[0]->replace(array('attr1' => 'replaced'));
        $entries[2]->delete(array('attr2'));
        $entries[2]->delete(array('attr3' => 'bar'));

        // open some file for writing, but in change mode
        $ldif = new Net_LDAP_LDIF('somewritefile.ldif', 'w', array('change' => true));
        if ($ldif->error()) die('ERROR: '.$error_o->getMessage());

        // write the data and check for error
        // you could pass one single Net_LDAP_Entry object or
        // several objects inside an array
        $ldif->write_entry($entries);
        if ($ldif->error()) die('WRITE ERROR: '.$error_o->getMessage());

        // Now, only two entries are contained in the LDIF file,
        // cn=foo,dc=example,dc=cno and cn=baz,dc=example,dc=cno.
        // cn=bar,dc=example,dc=cno had no changes and was skipped.
?>

Resulting LDIF change file

version: 1
dn: cn=foo,dc=example,dc=cno
changetype: modify
add: someattr
someattr: added
-
replace: attr1
attr1: replaced
-

dn: cn=baz,dc=example,dc=cno
changetype: modify
delete: attr2
-
delete: attr3
attr3: bar
-

Fetching LDIF data

Sometimes you are interested in the lines inside the LDIF file. For those cases you can use the current_lines() and next_lines() methods. They work in the current context, which may be confusing: current_lines() will always return the lines that have built up the current Net_LDAP_Entry object when called current_entry() after read_entry() has been called. next_lines() will always return the lines, that will build up the next entry from the current point of view, meaning "relative to the entry that was just been read". However, you can override this by activating the "force" parameter of next_lines() which allows you to loop over all entries. current_entry() behaves exactly like current_lines().

If you think, that the lines you have read would be better in form of an Net_LDAP_Entry object, use the parseLines() method to parse those lines into an entry. This is a good way if you need just a few specific entries of a large LDIF file.

Reading LDIF lines

<?php
// open some LDIF file for reading
// (error checking code is ommitted in this example for
//  better readability - in production, test for errors!)
$ldif = new Net_LDAP_LDIF('somefile.ldif', 'r');

// since nothing has been read until now, this will
// return an empty array
$empty_array = $ldif->current_lines();

// so let's read the first entries data
$first_entry_lines = $ldif->next_lines();

// if we call it again, we will not read ahead to the
// second entry - we again read the first one!
$first_entry_lines_again = $ldif->next_lines();

// If we call current_lines() now, we haven't read ahead
// like we learned from the last statement.
$empty_array_again = $ldif->current_lines();

// If we want to shift, we must use
// the read_entry() method, which will read ahead.
$first_entry = $ldif->read_entry();

// Now, current_lines() returns the lines of the
// first entry and next_lines() the lines of the second:
$first_entry_lines  = $ldif->current_lines();
$second_entry_lines = $ldif->next_lines();

// There is another way to shift the lines which is faster if
// you are just interested in the LDIFs content - you
// need to pass the "force" parameter to next_lines():
$third_entry_lines  = $ldif->next_lines(true);
$fourth_entry_lines = $ldif->next_lines(true);
$fifth_entry_lines  = $ldif->next_lines(true);

// If you want to convert the lines to an Net_LDAP_Entry,
// you may do so anytime by using parseLines()
$fourth_entry = $ldif->parseLines($fourth_entry_lines);

// Since we shifted manually only the lines,
// current_lines() will return the lines that built up the
// last (e.g. the first entry) Net_LDAP_Entry object:
$first_entry_lines  = $ldif->current_lines();

// If we decide to read the next entry, we can do that:
$sixth_entry = $ldif->read_entry();

// current_lines() is shifted now:
$sixth_entry_lines = $ldif->current_lines();
?>