Differences

This shows you the differences between two versions of the page.

--- rfc:ldap_exop [2017/06/26 14:53] – Added functions definitions mcmic
+++ rfc:ldap_exop [2017/06/29 14:24] – mcmic
@@ Line 17: / Line 17: @@
 ===== New functions =====
+In all these functions $link should be a valid LDAP connection object with a user bound to it already.
 <code php>
 mixed ldap_exop(resource $link, string $reqoid [, string $reqdata [, string &$retoid [, string &$retdata]]])
 </code>
-Returns FALSE upon failure, TRUE upon success if $retoid is provided, and a result object otherwise (success with 3 params or less).
+Returns FALSE upon failure, TRUE upon success if $retoid is provided, and a result object otherwise (success with 3 params or less). Either fills $retoid and $retdata or returns a result object.
 <code php>
 bool ldap_parse_exop(resource $link, resource $result [, string &$retoid [, string &$retdata]])
 </code>
 Returns TRUE upon success and FALSE upon failure. Fills $retoid and $retdata with the data from $result object.
+This RFC also wish to introduce helper functions for common EXOP usage:
+<code php>
+bool ldap_exop_whoami(resource $link, string &$result)
+bool ldap_exop_passwd(resource $link, string $user, string $oldpw, string $newpw [, string &$genpw])
+</code>
+The first one would call whoami EXOP and return either the result or FALSE upon failure.
+The second one would call passwd EXOP and return TRUE or FALSE upon failure. If $newpw is empty, $genpw will be filled with the generated password for the user. If $user is empty, it affects the bound user.
+The author of the original patch stated that technically ldap_start_tls is an exop helper and therefore could be renamed ldap_exop_start_tls. We feel this would be a useless BC.
+The original patch (and current code) provided a possibility to get a result object from helpers as well, and provided ldap_parse_exop_* helpers to parse the result objects from these operations. We feel this is too complex and does not add anything to the RFC so we intend to leave them out.
+===== Examples =====
+<code php>
+// Call EXOP whoami and store the result in $identity
+if (ldap_exop($link, LDAP_EXOP_WHO_AM_I, NULL, NULL, $identity)) {
+  echo "Connected as $identity\n";
+} else {
+  echo "Operation failed\n";
+}
+// Same thing using a result object
+$r = ldap_exop($link, LDAP_EXOP_WHO_AM_I);
+if (($r !== FALSE) && ldap_parse_exop($link, $r, $retoid, $retdata)) {
+  echo "Connected as $retdata\n";
+} else {
+  echo "Operation failed\n";
+}
+// Same thing with the helper
+$identity = ldap_exop_whoami($link);
+if ($identity !== FALSE) {
+  echo "Connected as $identity\n";
+} else {
+  echo "Operation failed\n";
+}
+// Changing password with the helper
+if (ldap_exop_passwd($link, 'uid=johndoe,dc=example,dc=com', '', 'newpassword')) {
+  echo "Password changed\n";
+} else {
+  echo "Operation failed\n";
+}
+</code>
 ===== Backward Incompatible Changes =====
@@ Line 30: / Line 73: @@
 ===== Proposed PHP Version(s) =====
-.2 if possible, 7.3/8 otherwise
+Next PHP 7.x release
 ===== RFC Impact =====
@@ Line 49: / Line 92: @@
 ===== Open Issues =====
   - Should the function names contain the word "exop" or is it a technical detail which should be hidden from the developer?
-  - Should we include a constant for LDAP_EXOP_REFRESH, for the sake of completeness, even if this EXOP won’t be used by PHP code as all PHP LDAP operations are synchrone (in the current code state).
+  - Should we include a constant for LDAP_EXOP_CANCEL, for the sake of completeness, even if this EXOP won’t be used by PHP code as all PHP LDAP operations are synchrone (in the current code state).
+  - Should helper functions return a mixed, or a boolean and have an out parameter? ("mixed ldap_exop_whoami($link)" vs "bool ldap_exop_whoami($link, &$result)")
+  - How would someone go about generating the needed ber-encoded data to pass ldap_exop in PHP? Should this RFC also define functions to handle ber-encoded data?
+  - The $retoid field seems useless for all EXOPs listed in the constant section, they either leave it empty or fill it with the same value as $reqoid. So maybe this field should be moved to the last position to be easily omitted. But this may result in a less natural order: //reqoid, reqdata, retdata, retoid// (though most of the time it will be //reqoid, reqdata, retdata//).
+  - How should error handling works? Original patch throws E_WARNING for all errors and failures, which seems a bad idea. Maybe filling the error so that error_get_last() gives the right information when a function of this RFC returns FALSE would be enough? Or should be uses exceptions?
 ===== Unaffected PHP Functionality =====

Differences

Page Tools