rfc:allow_null

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
rfc:allow_null [2021/12/30 02:59] – Draft updates craigfrancisrfc:allow_null [2022/04/05 17:49] (current) – superseded craigfrancis
Line 1: Line 1:
 ====== PHP RFC: Allow NULL ====== ====== PHP RFC: Allow NULL ======
  
-  * Version: 1.0+  * Version: 1.3
   * Voting Start: ?   * Voting Start: ?
   * Voting End: ?   * Voting End: ?
   * RFC Started: 2021-12-23   * RFC Started: 2021-12-23
-  * RFC Updated: 2021-12-23+  * RFC Updated: 2022-02-20
   * Author: Craig Francis, craig#at#craigfrancis.co.uk   * Author: Craig Francis, craig#at#craigfrancis.co.uk
   * Status: Draft   * Status: Draft
Line 11: Line 11:
   * GitHub Repo: https://github.com/craigfrancis/php-allow-null-rfc   * GitHub Repo: https://github.com/craigfrancis/php-allow-null-rfc
   * Implementation: ?   * Implementation: ?
 +
 +----
 +
 +This RFC has been superseded by [[https://wiki.php.net/rfc/null_coercion_consistency|NULL Coercion Consistency]]
 +
 +----
  
 ===== Introduction ===== ===== Introduction =====
  
-PHP 8.1 introduced "Deprecate passing null to non-nullable arguments of internal functions" ([[https://externals.io/message/112327|short discussion]]), which is making it difficult for developers to upgrade.+PHP 8.1 introduced "Deprecate passing null to non-nullable arguments of internal functions" ([[https://externals.io/message/112327|short discussion]]), which is making it difficult (time consuming) for developers to upgrade. 
 + 
 +This has introduced an inconstancy when not using //strict_types=1//, because most variables types (e.g. integers) can be coerced to the relevant type, but //NULL// has been deprecated.
  
-Often //NULL// is used for undefined //GET/////POST/////COOKIE// variables:+In PHP //NULL// is often used to represent something; e.g. when a //GET/////POST/////COOKIE// variable is undefined:
  
 <code php> <code php>
Line 27: Line 35:
 </code> </code>
  
-And //NULL// can be returned from many functions, e.g.+And //NULL// can be returned from functions, e.g.
  
   * //array_pop()//   * //array_pop()//
Line 35: Line 43:
   * //json_decode()//   * //json_decode()//
  
-Which makes it common for developers to pass potential //NULL// values to these internal functions, e.g.+This makes it common for //NULL// to be passed to many internal functions, e.g.
  
 <code php> <code php>
Line 50: Line 58:
 </code> </code>
  
-Currently this affects those using PHP 8.1 with //E_DEPRECATED//, but it implies everyone will need to modify their code in the future.+Developers also use //NULL// to skip certain parameters, e.g. //$additional_headers// in //mail()//.
  
-It also applies even if they are not using //strict_types=1//.+Where //NULL// has always been coerced into an empty string, the integer 0, the boolean false, etc.
  
-And while the individual modifications are easy, there are many of them, they are difficult to find, and often pointless (e.g. //urlencode(strval($name))//).+Currently the deprecation notices only affect those using PHP 8.1 with //E_DEPRECATED//, but it implies everyone will need to modify their code to avoid **Fatal Errors** in PHP 9.0.
  
-Without the changes listed below, developers will need to either use these deprecation warnings, or use strict Static Analysis (one that can determine when a variable can be //NULL//; e.g. Psalm at [[https://psalm.dev/docs/running_psalm/error_levels/|level 3]], with no baseline).+Developers using //strict_types=1// may find some value in this, but it's excessive and inconstant for everyone else. 
 + 
 +And while individual changes are easy, there are many of them (time consuming), difficult to find, and often pointless, e.g. 
 + 
 +  * urlencode(strval($name)); 
 +  * urlencode((string) $name); 
 +  * urlencode($name ?? ''); 
 + 
 +To find these issues, developers need to either - use these deprecation notices, or use very strict Static Analysis (one that can determine when a variable can be //NULL//; e.g. Psalm at [[https://psalm.dev/docs/running_psalm/error_levels/|level 3]], with no baseline). 
 + 
 +It's worth noting that some parameters, like //$separator// in //explode()//, already have a "cannot be empty" Fatal Error. So it might be useful to have a separate RFC to update some of these parameters to consistently reject NULL **or** Empty Strings, e.g. //$needle// in //strpos()// and //$json// in //json_decode()//.
  
 ===== Proposal ===== ===== Proposal =====
  
-Update **some** internal function parameters to accept NULL, to reduce the burden for developers upgrading.+There are 3 possible approaches:
  
-While this is in Draft, the [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-change.md|list of functions is hosted on GitHub]] (pull requests welcome):+  - NULL triggers a Fatal Error with strict_types=1, otherwise allow coercion (like how integers can be coerced to a string). 
 +  - NULL triggers a Fatal Error for everyone, but update some parameters to explicitly allow NULL (e.g. //?string//). 
 +  - NULL triggers a Fatal Error for everyone (forget about backwards compatibility).
  
-===== Decision Process =====+This needs to be done before the eventual end of the deprecation period, and //TypeError// exceptions are thrown.
  
-Does the parameter work with //NULL//, in the same way that it would if an empty string is provided? e.g.+If we choose to "update some parameters to explicitly allow NULL", there is a [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-change.md|draft list of functions]], where the **bold** are being proposed (currently only includes string parameters). [[https://github.com/craigfrancis/php-allow-null-rfc/issues|Suggestions]] and [[https://github.com/craigfrancis/php-allow-null-rfc/pulls|Pull Requests]] welcome.
  
-  - //preg_match()// should continue to deprecate //NULL// for //$pattern//, whereas //$subject// should accept //NULL//. +There is also a [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-maybe.md|Maybe List]], where the more questionable arguments end with a "!". For example, //strrpos()// accepting an empty string for //$needle// is wired in itself, and //sodium_crypto_box_open()// should never receive a blank //$ciphertext//. And there is an [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-other.md|Other List]], which can be ignored.
-  - //hash_file()// should continue to deprecate //NULL// for the //$filename//. +
-  - //hash()// should accept //NULL// for //$data//. +
-  - //substr_count()// requires a non-empty string //$needle// (continue to deprecate //NULL//). +
-  - //mb_convert_encoding()// requires a valid encoding for //$to_encoding// (continue to deprecate //NULL//).+
  
-You could argue some function parameters should not accept an empty string either (e.g. //strpos()// accepting an empty string for //$needle//), but that would require different RFCs, where backwards compatibility would need to be discussed.+===== Decision Process ===== 
 + 
 +Does //NULL// for this parameter justify a Fatal Error? e.g. 
 + 
 +  - //preg_match()// should **deprecate** //NULL// for //$pattern// ("empty regular expression" warning). 
 +  - //preg_match()// should **accept** //NULL// for //$subject// (e.g. checking user input). 
 +  - //hash_file()// should **deprecate** //NULL// for the //$filename//. 
 +  - //hash()// should **accept** //NULL// for //$data//. 
 +  - //substr_count()// should **deprecate** //NULL// for //$needle// ("$needle cannot be empty" error). 
 +  - //mb_convert_encoding()// should **deprecate** //NULL// for //$to_encoding// (requires a valid encoding).
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 100: Line 125:
 ===== Open Issues ===== ===== Open Issues =====
  
-TODO+Is the [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-change.md|list of functions]] complete?
  
 ===== Future Scope ===== ===== Future Scope =====
  
-None+Some function parameters could be updated to complain when an //NULL// **or** //Empty String// is provided; e.g. //$method// in //method_exists()//, or //$characters// in //trim()//.
  
 ===== Voting ===== ===== Voting =====
Line 112: Line 137:
 TODO TODO
  
-===== Patches and Tests =====+===== Tests =====
  
-TODO+To get and **Test** the list of functions, I wrote a script to //get_defined_functions()//, then used //ReflectionFunction()// to identify parameters that accepted the 'string' type, and not //->allowsNull()//. This resulted in the [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-change.md|list of functions to change]], where I manually removed the [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions-other.md|functions that shouldn't be changed]], and updated the script to test every argument (to see that it complained with //NULL//, and the output remained the same) - [[https://github.com/craigfrancis/php-allow-null-rfc/blob/main/functions.php|Source]].
  
 ===== Implementation ===== ===== Implementation =====
  
-TODO+https://github.com/craigfrancis/php-src/compare/master...allow-null 
 + 
 +This patch defines //Z_PARAM_STR_ALLOW_NULL//. 
 + 
 +It works a bit like //Z_PARAM_STR_OR_NULL//, but it will return an empty string instead of //NULL//. 
 + 
 +It's a fairly easy drop in replacement for //Z_PARAM_STR//, e.g. [[https://github.com/php/php-src/blob/7b90ebeb3f954123915f6d62fb7b2cd3fdf3c6ec/ext/standard/html.c#L1324|htmlspecialchars()]].
  
 ===== Rejected Features ===== ===== Rejected Features =====
rfc/allow_null.1640833191.txt.gz · Last modified: 2021/12/30 02:59 by craigfrancis

Page Tools