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
