*    Updated the phpDoc comments to match the code
*    Added return statements
*    Added return values

ldap_connect() can return false too

The equation was wrong.. exceeding means > not >=

Working toward some of the requested tasks in
https://github.com/simplesamlphp/simplesamlphp/wiki/List-of-tasks

searchformultiple() will loop over all the configured base dn's to
search in. However, it would break on the first search that does
not return `false`. A search that yields 0 hits is not `false`, however
(it is only false when an error occurred). So when using more than one
base, users would not be found if they were part of the second or later
base, which is contrary to the intention.

This is now changed so the loop breaks when the result is not false, and
the number of found results is > 0.

I have been maintaining the PHP LDAP EXOP patch for a few years,
which include the ldapwhoami() function. This has finally made its
way into PHP distribution and will be available in PHP 7.3, but
with a modified prototype.

This changes adapts to this API change. While there, also update
exception handling on par with recent SimpleSAMLphp code.

For #458

In the LDAP class, the password should only be escaped if it's not null, so that we don't try to bind with an empty password if none was provided. This fixes #366 and closes #370.

(being respectful with occurences that might change the behaviour, i.e. default database prefixes)

Fixed to follow PSR-2 coding guidelines, proper indentation and a minor fix in equality operand (== vs ===)

The `makeException` function returns an instantiated object, so the
caller shouldn't also call `new`.

(as suggested by jhaar in issue #120 and used by us)

Since PHP 5.3 is required, there's no need to treat users of 5.1.2-5.2 specially. Also we can safely use LDAP_OPT_NETWORK_TIMEOUT now.

Schedule SimpleSAML_Utilities:: arrayize() for removal.