rfc:ldap_exop

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
rfc:ldap_exop [2017/06/28 08:59]
mcmic Added issue about error handling
rfc:ldap_exop [2017/07/13 08:48]
mcmic
Line 3: Line 3:
   * Date: 2017-06-26   * Date: 2017-06-26
   * Author: Côme Chilliet, mcmic@php.net   * Author: Côme Chilliet, mcmic@php.net
-  * Status: ​Draft+  * Status: ​Merged
   * First Published at: http://​wiki.php.net/​rfc/​ldap_exop   * First Published at: http://​wiki.php.net/​rfc/​ldap_exop
  
Line 19: Line 19:
 In all these functions $link should be a valid LDAP connection object with a user bound to it already. In all these functions $link should be a valid LDAP connection object with a user bound to it already.
 <code php> <code php>
-mixed ldap_exop(resource $link, string $reqoid [, string $reqdata [, string &$retoid ​[, string &$retdata]]])+mixed ldap_exop(resource $link, string $reqoid [, string $reqdata [, string &$retdata ​[, string &$retoid]]])
 </​code>​ </​code>​
-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.+Returns FALSE upon failure, TRUE upon success if $retdata ​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> <code php>
-bool ldap_parse_exop(resource $link, resource $result [, string &$retoid ​[, string &$retdata]])+bool ldap_parse_exop(resource $link, resource $result [, string &$retdata ​[, string &$retoid]])
 </​code>​ </​code>​
 Returns TRUE upon success and FALSE upon failure. Fills $retoid and $retdata with the data from $result object. Returns TRUE upon success and FALSE upon failure. Fills $retoid and $retdata with the data from $result object.
 +
 +Note that $retoid is useless in most cases, EXOPs usually leave it empty or fill it with $reqoid. This is why it’s in last position.
  
 This RFC also wish to introduce helper functions for common EXOP usage: This RFC also wish to introduce helper functions for common EXOP usage:
 <code php> <code php>
-mixed ldap_exop_whoami(resource $link) +bool|string ​ldap_exop_whoami(resource $link) 
-bool ldap_exop_passwd(resource $link, string $user, string $oldpw, ​string $newpw ​[string ​&$genpw])+bool|string ​ldap_exop_passwd(resource $link, ​[string $user, ​[string $oldpw, [string $newpw]]])
 </​code>​ </​code>​
-The first one would call whoami EXOP and return either ​the result ​or FALSE upon failure. +The first one would call whoami EXOP and returns ​the result. Returns ​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 second one would call passwd EXOP and return TRUE or FALSE upon failure. If $newpw is empty, ​returns ​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 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. 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.
 +
 +For consistency with existing ldap functions, theses function may produce E_WARNING in case of error or failure.
 +The safe way to use them is to use @ when calling them. ldap_error() can be used to get the last LDAP error in cases where it makes sense.
  
 ===== Examples ===== ===== Examples =====
 <code php> <code php>
 // Call EXOP whoami and store the result in $identity // Call EXOP whoami and store the result in $identity
-if (ldap_exop($link,​ LDAP_EXOP_WHO_AM_I, NULL, NULL, $identity)) {+if (ldap_exop($link,​ LDAP_EXOP_WHO_AM_I,​ NULL, $identity)) {
   echo "​Connected as $identity\n";​   echo "​Connected as $identity\n";​
 } else { } else {
Line 49: Line 54:
 // Same thing using a result object // Same thing using a result object
 $r = ldap_exop($link,​ LDAP_EXOP_WHO_AM_I);​ $r = ldap_exop($link,​ LDAP_EXOP_WHO_AM_I);​
-if (($r !== FALSE) && ldap_parse_exop($link,​ $r, $retoid, $retdata)) {+if (($r !== FALSE) && ldap_parse_exop($link,​ $r, $retdata)) {
   echo "​Connected as $retdata\n";​   echo "​Connected as $retdata\n";​
 } else { } else {
Line 55: Line 60:
 } }
 // Same thing with the helper // Same thing with the helper
-$identity = ldap_exop_whoami($link); +if (ldap_exop_whoami($link$identity)) {
-if ($identity ​!== FALSE) {+
   echo "​Connected as $identity\n";​   echo "​Connected as $identity\n";​
 } else { } else {
Line 91: Line 95:
  
 ===== Open Issues ===== ===== 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_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 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 ===== ===== Unaffected PHP Functionality =====
Line 114: Line 113:
  
 ===== Implementation ===== ===== Implementation =====
-After the project is implemented,​ this section should contain ​ +Merged in PHP 7.2 
-  the version(s) it was merged to +https://​github.com/​php/​php-src/​pull/​2608 
-  - a link to the git commit(s)+
   - a link to the PHP manual entry for the feature   - a link to the PHP manual entry for the feature
-  - a link to the language specification section (if any) 
  
 ===== References ===== ===== References =====
rfc/ldap_exop.txt · Last modified: 2017/09/22 13:28 (external edit)