Add support for parallel searches

[robertrossmann]

This is a feature proposal. Comments and ideas are encouraged.

PHP allows doing parallel searches. This could greatly enhance application's performance in situations where multiple search requests need to be issued.

Currently, the only way to perform parallel search is to gather the underlying ldap link resources with Ldap::getResource() and calling ldap_search() directly. This, however, breaks the purpose of having a testable ldap interface. As such, support for this feature should be added into the library.

A proposed API could look like this:

1. A new method is introduced, Ldap::parallelSearch() (or just Ldap::parallel()) with parameter signature identical to that of Ldap::ldapSearch()
2. Each call to this method would store the parameters in an array for later use (i.e. in a protected Ldap::$parallels property)

3. Once a call to Ldap::ldapSearch() is made (without arguments), a parallel search is executed with the params queued up in Ldap::$parallels and the results are returned in an array. The aforementioned protected property is emptied/reset.

   Caveats

   • The above proposal would only work with doing parallel searches on the same ldap link, although PHP has no such limitation. This is not a big deal for Active Directory (you can always search the Global Catalog), but might be a problem for multi-domain setups for i.e. OpenLDAP users.
   • PHP does not allow retrieving specific sets of attributes for individual searches, i.e. you cannot tell PHP to retrieve only objectClass for first search and only objectCategory for the second search. I filed a PHP bug ages ago, but so far no progress has been made. In the past, I dealt with this by doing a union on the requested attributes, but this is somewhat unintuitive. A better approach would be to change the proposed API to not accept $attributes parameter in calls to Ldap::parallel() and only accept it once the Ldap::ldapSearch() method is called, i.e.:

   // Example. Actual method signatures may vary.
   $ldap->parallel('DC=example,DC=com', 'objectClass=user', Ldap::SCOPE_SUBTREE);
   $ldap->parallel('DC=example,DC=com', 'objectCategory=Person', Ldap::SCOPE_SUBTREE);
   $ldap->ldapSearch(['objectClass', 'objectCategory', 'cn']);

[Furgas]

Working with multiple Ldap instances calls for specialized class for this, or at least some static method(s).

Specialized class:

$parallelSearch = new ParallelSearch(Ldap:SCOPE_SUBTREE); //scope must be the same
$parallelSearch->add($ldap1, 'DC=example,DC=com', 'objectClass=user');
$parallelSearch->add($ldap2, 'DC=example,DC=com', 'objectCategory=Person');
$results = $parallelSearch->perform($attributes, $attrsOnly, $sizeLimit, $timeLimit, $deref);
$entries1 = $results[0]->getEntries();
$entries2 = $results[1]->getEntries();

Static methods:

Ldap::addParallelSearch($ldap1, 'DC=example,DC=com', 'objectClass=user');
Ldap::addParallelSearch($ldap2, 'DC=example,DC=com', 'objectCategory=Person');
$results = Ldap::performParallelSearch($attributes, $scope, $attrsOnly, $sizeLimit, $timeLimit, $deref); //possible magic static methods for each scope
$entries1 = $results[0]->getEntries();
$entries2 = $results[1]->getEntries();