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/26 14:37]
mcmic
rfc:ldap_exop [2017/09/22 13:28] (current)
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 15: Line 15:
 This RFC intends to add support for EXOP in php-ldap. This RFC intends to add support for EXOP in php-ldap.
 It is based on a patch for php-ldap which is more than 10 years old and we are trying to adapt it for current code base. It is based on a patch for php-ldap which is more than 10 years old and we are trying to adapt it for current code base.
 +
 +===== 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 &​$retdata [, string &​$retoid]]])
 +</​code>​
 +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>
 +bool ldap_parse_exop(resource $link, resource $result [, string &​$retdata [, string &​$retoid]])
 +</​code>​
 +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:
 +<code php>
 +bool|string ldap_exop_whoami(resource $link)
 +bool|string ldap_exop_passwd(resource $link, [string $user, [string $oldpw, [string $newpw]]])
 +</​code>​
 +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, 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 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 =====
 +<code php>
 +// Call EXOP whoami and store the result in $identity
 +if (ldap_exop($link,​ LDAP_EXOP_WHO_AM_I,​ 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, $retdata)) {
 +  echo "​Connected as $retdata\n";​
 +} else {
 +  echo "​Operation failed\n";​
 +}
 +// Same thing with the helper
 +if (ldap_exop_whoami($link,​ $identity)) {
 +  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 ===== ===== Backward Incompatible Changes =====
Line 20: Line 77:
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
-7.2 if possible, 7.3/8 otherwise+Next PHP 7.x release
  
 ===== RFC Impact ===== ===== RFC Impact =====
 ==== To SAPIs ==== ==== To SAPIs ====
-Describe the impact ​to CLI, Development web server, embedded PHP etc.+No impact
  
 ==== To Existing Extensions ==== ==== To Existing Extensions ====
Line 38: 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_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).+
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
Line 45: Line 101:
  
 ===== Future Scope ===== ===== Future Scope =====
-This sections details areas where the feature might be improved in future, ​but that are not currently proposed in this RFC.+Support for more EXOP could be added by adding other helper methods or other oid constants. 
 +Support for clients/​servers controls should be added but will be part of an other RFC.
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 53: Line 110:
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
-Links to any external patches and tests go here. +https://​github.com/​MCMic/​php-src/​tree/​ldap_exop
- +
-If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed. +
- +
-Make it clear if the patch is intended to be the final patch, or is just a prototype. +
- +
-For changes affecting the core language, you should also provide a patch for the language specification.+
  
 ===== 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 =====
-Links to external references, discussions or RFCs+http://​grokbase.com/​t/​php/​php-internals/​05bn5vc440/​discussion-of-ldap-api-extensions 
 +https://​bugs.php.net/​bug.php?​id=69445
  
 ===== Rejected Features ===== ===== Rejected Features =====
-Keep this updated with features that were discussed on the mail lists.+None
rfc/ldap_exop.1498487853.txt.gz · Last modified: 2017/09/22 13:28 (external edit)