Net::LDAP::Class::Iterator - iterate over Net::LDAP::Class objects


 my $iterator = $user->groups_iterator;
 while ( my $group = $iterator->next ) {
    # $group isa Net::LDAP::Class::Group
 printf("%d groups found\n", $iterator->count);


Net::LDAP::Class::Iterator handles paged searching using Net::LDAP::Control::Paged.


Many of the relationship methods in Net::LDAP::Class get and set arrays or array refs of related objects. For small (<1000) data sets arrays are just fine but as data sets scale, different techniques become necessary. An iterator has a big resource advantage over an array: instead of holding all the related objects in memory at once, as an array does, an iterator reads one object at a time from the LDAP server.

For example, if you want to look at all the users who are members of a group, and the number of users is large (>1000), some LDAP servers (Active Directory in particular) won't return all of your user objects in a single query. Instead, the results must be paged using Net::LDAP::Control::Paged. You'll see the evidence of this if you call the following code against Active Directory with a group of more than 1000 users.

 my $group = MyADGroup->new( cn => 'myBigGroup', ldap => $ldap )->read;
 my $users = $group->users;  # bitten by AD! returns an empty array ref!
 foreach my $user (@$users) {
   # nothing here -- the array is empty

The call to $group->users returns an empty array because Active Directory refuses to return more than 1000 results at a time. (NOTE the number 1000 is the default maximum; your server may be configured differently.)

So an iterator to the rescue!

 my $users = $group->users_iterator;
 while ( my $user = $users->next ) {
    # do something with $user
 printf("We saw %d users in group %s\n", $users->count, $group->name);

You might ask, why bother with arrays at all if iterators are so great. The answer is convenience. For small data sets, arrays are convenient, especially if you intend to do things with subsets of them at a time. Of course, you could do this:

 my $users = $group->users_iterator;
 my @allusers;
 while ( my $user = $users->next ) {
     push @allusers, $user;

But then you've negated one of the advantages of the iterator: it is less resource-intensive. But hey, if you've got the memory, honey, Perl's got the time.



Accessor for Net::LDAP object. Set in new().


Required in new().


The size of the Net::LDAP::Control::Paged set. Default is 500. Set in new().


The search filter to use. Set in new().


The class to bless results into. Set in new().


Checks that alll required params are defined and sets up the pager.


Returns the number of iterations performed.


Returns true (1) if all the results for this iterator have been seen, false (0) otherwise.


Returns the next Net::LDAP::Class object from the pager. Returns undef if no more results are found.


Tell the server you're done iterating over results. This method is only necessary if you stop before exhausting all the results.


Peter Karman, <karman at>


Please report any bugs or feature requests to bug-net-ldap-class at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Net::LDAP::Class

You can also look for information at:


Copyright 2009 by Peter Karman.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Net::LDAP, Net::LDAP::Batch