rfc:skipparams

Differences

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

Link to this comparison view

rfc:skipparams [2012/05/12 01:15]
stas [Issues raised]
rfc:skipparams [2013/09/02 23:46] (current)
stas [Changelog]
Line 1: Line 1:
 ====== Skipping optional parameters for functions ====== ====== Skipping optional parameters for functions ======
-  * Version: ​1.0 +  * Version: ​2.0 
-  * Date: 2012-04-13+  * Date: 2013-09-01
   * Author: Stas Malyshev <​stas@php.net>​   * Author: Stas Malyshev <​stas@php.net>​
   * Status: Under Discussion   * Status: Under Discussion
-  * Implementation:​ https://​github.com/​smalyshev/​php-src/​tree/​skip_params +  * Implementation: ​https://​github.com/​php/​php-src/​pull/​426, ​https://​github.com/​smalyshev/​php-src/​tree/​skip_params
 ===== Introduction ===== ===== Introduction =====
  
Line 19: Line 18:
 The proposal is to allow skipping optional arguments in a call, thus making them assume default values as they do when they are not provided, like this: The proposal is to allow skipping optional arguments in a call, thus making them assume default values as they do when they are not provided, like this:
  
-      create_query("​deleted=0",​ "​name",,,​ /​*report_errors*/​ true);+      create_query("​deleted=0",​ "​name", ​defaultdefault, /​*report_errors*/​ true);
  
 This means that $join_type and $execute are going to use defaults. This means that $join_type and $execute are going to use defaults.
 Of course, if we ever get implementation of named parameters, it may also solve this problem, but until we do, this can be a partial solution. ​ Of course, if we ever get implementation of named parameters, it may also solve this problem, but until we do, this can be a partial solution. ​
  
-Only optional parameters can be skipped this way, skipping non-optional one will produce the same error it does now when function is not given engough ​parameters.+Only optional parameters can be skipped this way, skipping non-optional one will produce the same error it does now when function is not given enough ​parameters.
  
 ===== Implementation ===== ===== Implementation =====
Line 30: Line 29:
 On the engine level, it will be implemented by putting NULL in the place where the parameter is passed. Functions dealing with argument handling will be updated. On the engine level, it will be implemented by putting NULL in the place where the parameter is passed. Functions dealing with argument handling will be updated.
  
-See example implementation above. ​Tests for most use cases will be added shortly.+See example implementation above. ​See tests for examples of most common uses cases. ​
  
 ===== User functions ===== ===== User functions =====
Line 42: Line 41:
 Variadic functions will not return skipped parameters in argc and argv, effectively ignoring them, so: Variadic functions will not return skipped parameters in argc and argv, effectively ignoring them, so:
  
-       ​var_dump(2,,​1);​+       ​var_dump(2,​default,1);
  
 is the same as: is the same as:
Line 56: Line 55:
      }      }
  
-     ​test(1,,​4);​+     ​test(1,​default,4);
  
 will produce: will produce:
Line 79: Line 78:
 call_user_func will allow argument skipping directly: call_user_func will allow argument skipping directly:
  
-      call_user_func('​test',​ 42,,44);+      call_user_func('​test',​ 42, default, 44);
  
 with the same result. with the same result.
 +
 +===== Internal API changes =====
 +Parameters stored as zval** in the engine. For skipped parameter, the value stored is NULL instead of zval* to specific argument. The opcode putting NULL on the stack is implemented as znode type IS_UNUSED.
 +
 +zend_parse_parameter() would ignore parameters marked as default - meaning, it will not assign any value to the underlying variable. This is unless the parameter is marked as !, in which case the parameter would be nullified just as if null were passed. This means you can not have variables marked as ! with different behavior between null and '​default',​ but I did not find any such cases to be required. ​
 +
 +For variadic parameters like + and *, skipped parameters will be ignored and not included in the list as if they were not passed. In other words, + and * will never return NULLs among parameters. ​
 +
 +If certain function wants to disallow skipping parameters, it should use option ZEND_PARSE_PARAMS_NODEFAULT with zend_parse_parameters_ex(). In this case, skipped parameters will cause . For older APIs, zend_get_parameters_array_nodefault() is available which will fail with E_WARNING "​Parameter %d missing"​ if any skipped parameters are passed (i.e. would never return NULLs as parameters).
 +
 +ZEND_NUM_ARGS() is always the number of parameters in function call, so skipped parameters are counted there. But trying to get a skipped parameter with API functions will produce NULL. 
  
 ===== User request examples ===== ===== User request examples =====
Line 93: Line 103:
   * http://​stackoverflow.com/​q/​4681987/​214196 (for Delphi)   * http://​stackoverflow.com/​q/​4681987/​214196 (for Delphi)
   * http://​stackoverflow.com/​q/​4435918/​214196 (for AS)   * http://​stackoverflow.com/​q/​4435918/​214196 (for AS)
 +  * http://​stackoverflow.com/​q/​812058/​214196 (for Ruby)
 ===== Issues raised ===== ===== Issues raised =====
-    ​* Using "​default"​ instead of skipping parameter +    * Support for internal functions doing manual ZEND_NUM_ARGS(). I've looked into all functions in the standard distribution,​ but PECL extensions that are not using zend_parse_parameters or do weird things with zval-type ones without properly initializing them or checking the output results, may require fixing, otherwise they may crash if "​default"​ is passed to them due to null pointer reference. This crash doesn'​t seem to be dangerous security-wise,​ but would of course be unpleasant. ​
-    ​* Support for internal functions doing manual ZEND_NUM_ARGS()+
  
 ===== Changelog ===== ===== Changelog =====
  
-* 2012-04-13 First draft.+  ​* 2012-04-13 First draft. 
 +  * 2012-07-07 Changed empty parameter to use '​default'​ 
 +  * 2013-09-01 Added Zend API description
rfc/skipparams.1336778146.txt.gz · Last modified: 2012/05/12 01:15 by stas