LDIF support was added to Net_LDAP2 in release 1.1.0a1.

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

 # # 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.

 # # 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

Before we can start using Net_LDAP2_LDIF we must say some short words about how error handling works. Net_LDAP2_LDIF was designed to have mostly the same API as the original PERL Net::LDAP::LDIF has. Because of this, the methods of Net_LDAP2_LDIF do not return a Net_LDAP2_Error object. You must use the error() method that will return a Net_LDAP2_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.

Regardless if you want to read or write a LDIF file, you always have to use the constructor of Net_LDAP2_LDIF to initialize your access to the LDIF file. You need to pass at least one parameter to Net_LDAP2_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_LDAP2_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_LDAP2_LDIF, you can use handle() to get the filehandle from the first instance.

One of the two modes how Net_LDAP2_LDIF can be used is to read a LDIF file and parse its contents into an array of Net_LDAP2_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:

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.

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.

 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 -

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_LDAP2_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_LDAP2_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.