new LDAP function: ldap_modify_batch

Hi,

yesterday, I submitted a patch to add a batch modification function to the
LDAP extension:

https://bugs.php.net/bug.php?id=64317

IMNSHO, this would be a very useful addition to PHP’s LDAP API (and I think
the submitter of bug 31209, among others, would agree with me), so I’d like
to ignite a discussion about it, collect feedback, and have it added to PHP
as soon as possible. ;-)

This email serves as a description of my motivation and addresses a few
points of contention that might arise.

== Motivation ==

PHP’s LDAP extension already allows many modification operations on an
LDAP-enabled directory service. In fact, all the basic features
(create/delete object, add/remove/replace attribute values) are available.
However, LDAP itself allows to combine multiple modifications into one
request, and some directory services (e.g. Active Directory and,
apparently, Novell NDS) require this for more delicate operations such as
changing (not resetting) a user’s password.

My original motivation was wanting to write a password-changing page for an
Active Directory domain. However, I tried to keep the interface as generic
as possible, since I obviously can’t think of every possible use case.

== Interface ==

(This is, of course, subject to change, depending on your feedback.)

The API is as follows:

bool ldap_modify_batch(resource $connection, string $dn, array
$modifications);

$connection contains the connection to the LDAP server, as returned by
ldap_connect.

$dn contains the Distinguished Name of the object to modify.

$modifications is an array of modifications. Each modification is an
associative array containing values for the keys "attrib" (which attribute
to modify), "modtype" (what kind of modification is being performed) and
"values" (array of values to add, remove, or use as a replacement).

A practical example of an Active Directory password modification is
included in the bug report linked above; an example of all the kinds of
modifications available is directly in the implementation’s source code (I
used it as a reference during implementation).

== Points of Discussion ==

• The structure of $modifications. I wouldn’t be surprised if an
  array-of-arrays-of-arrays structure is frowned upon by the PHP maintainers.
  I’m also unsure whether the hard-coded key strings ("attrib", "modtype" and
  "values") are the right way to go. (I have defined symbolic constants for
  them as well, but I think we should ultimately decide whether we want
  hard-coded strings or symbolic constants [which would then probably be
  integers and not strings]).

• Type inflexibility. Currently, I enforce that both the value of "attrib"
  and the elements of the "values" array must be strings. Given PHP’s weak
  typing, would it make sense to have them automatically converted if they
  are of any other type? Or should this be left to the user (who is then more
  motivated to make sure the data they are storing is correctly formatted)?

• Validate-then-perform. The function, as I have written it, first performs
  all the necessary validations and then only assembles all the data for the
  C API. I chose this approach because it makes cleanup easier: if I perform
  validation after allocating a few things, I need to keep track of what I
  have allocated and what not. If I validate first, I can allocate everything
  more or less at one shot and then have only one code path to free
  everything again. On the other hand, this division means I have to iterate
  through each array twice, which might slightly reduce performance.

• No documentation. I haven’t written any documentation for
  ldap_modify_batch. Yet. Once I have received enough feedback, especially on
  the points above, I’m ready to write a page documenting it as well. (I’m
  sure this is an important criterion when deciding whether to accept a new
  function into the API.)

• Utility functions. I have written three utility functions to make my life
  easier, but I might have duplicated some code in the process. If the Zend
  API already contains equivalents of _ldap_str_equal_to_const,
  _ldap_strlen_max or _ldap_hash_fetch, please point me in the right
  direction.

Thanks for reading through all this, and I’m looking forward to your
feedback!

Cheers,
~~ Ondra Hošek