Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:66326
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.215.172 as permitted sender)
MIME-Version: 1.0
Date: Thu, 28 Feb 2013 14:54:30 +0100
Message-ID: <CAJLZGm+uBQX=Kw50oHMBepUnkFZOuXCpNwMcd6ZQ2BGrsvGsZQ@mail.gmail.com>
To: PHP Internals List <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=047d7b6704cd0fd07604d6c93ccc
Subject: new LDAP function: ldap_modify_batch
From: ondra.hosek@gmail.com (=?UTF-8?B?T25kxZllaiBIb8WhZWs=?=)

--047d7b6704cd0fd07604d6c93ccc
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Hi,

yesterday, I submitted a patch to add a batch modification function to the
LDAP extension:

https://bugs.php.net/bug.php?id=3D64317

IMNSHO, this would be a very useful addition to PHP=E2=80=99s LDAP API (and=
 I think
the submitter of bug 31209, among others, would agree with me), so I=E2=80=
=99d 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.

=3D=3D Motivation =3D=3D

PHP=E2=80=99s 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=E2=80=99s 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=E2=80=99t think of every possible use ca=
se.

=3D=3D Interface =3D=3D

(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=E2=80=99s source =
code (I
used it as a reference during implementation).

=3D=3D Points of Discussion =3D=3D

* The structure of $modifications. I wouldn=E2=80=99t be surprised if an
array-of-arrays-of-arrays structure is frowned upon by the PHP maintainers.
I=E2=80=99m also unsure whether the hard-coded key strings ("attrib", "modt=
ype" 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=E2=80=99s=
 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=E2=80=99t written any documentation for
ldap_modify_batch. Yet. Once I have received enough feedback, especially on
the points above, I=E2=80=99m ready to write a page documenting it as well.=
 (I=E2=80=99m
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=E2=80=99m looking forward to you=
r
feedback!

Cheers,
~~ Ondra Ho=C5=A1ek

--047d7b6704cd0fd07604d6c93ccc--