rfc:dbc

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:dbc [2015/02/12 13:43] – francoisrfc:dbc [2018/03/01 23:19] (current) – Typo "Under Discussion" carusogabriel
Line 3: Line 3:
   * Date: 2015-02-09   * Date: 2015-02-09
   * Author: François Laupretre <francois@php.net>   * Author: François Laupretre <francois@php.net>
-  * Status: Draft+  * Status: Under Discussion
   * First Published at: http://wiki.php.net/rfc/dbc   * First Published at: http://wiki.php.net/rfc/dbc
 +
 +  This RFC is waiting for the decisions that will be made about scalar
 +  type hinting. The reason is that the design and syntax
 +  decisions that will be made about scalar type hinting heavily impact the
 +  contents of this RFC. Proposal is subject to be changed according scalar type 
 +  hinting implementation.
  
 ===== Preamble ===== ===== Preamble =====
 +
 +This RFC is part of "Design by Contract Introduction" RFC
 +
 +  * https://wiki.php.net/rfc/introduce_design_by_contract
 +
 +There is alternative implementation proposal by "Definition"
 +
 +  * https://wiki.php.net/rfc/dbc2
 +
  
 The original idea of introducing DbC in PHP comes from Yasuo Ohgaki The original idea of introducing DbC in PHP comes from Yasuo Ohgaki
Line 14: Line 29:
 doc comments. This is the present document. doc comments. This is the present document.
  
-While we agree on the concept, Yasuo is preferring a D-like syntax, which he's proposing in [another RFC|https://wiki.php.net/rfc/dbc2].+While we agree on the concept, Yasuo is preferring a D-like syntax, which he's proposing in [[https://wiki.php.net/rfc/dbc2|another RFC]].
 IMO, adopting the D syntax would be fine if we designed the language from scratch, but is not the IMO, adopting the D syntax would be fine if we designed the language from scratch, but is not the
 best way to include the concept in PHP (more details below). best way to include the concept in PHP (more details below).
Line 22: Line 37:
 For more than 10 years (since PHP 5 was released), the PHP core community has For more than 10 years (since PHP 5 was released), the PHP core community has
 seen a lot of discussions about strict vs loose typing, type hinting and seen a lot of discussions about strict vs loose typing, type hinting and
-related features. Through these discussions, developers are acutally searching for a way to help reduce coding errors by detecting+related features. Through these discussions, developers are actually searching for a way to help reduce coding errors by detecting
 them as early as possible. Strictifying types is an approach but, unfortunately, it does not fit them as early as possible. Strictifying types is an approach but, unfortunately, it does not fit
 so well with PHP as a loose-typed language. so well with PHP as a loose-typed language.
Line 62: Line 77:
 * This function computes the area of a triangle using Heron's formula. * This function computes the area of a triangle using Heron's formula.
 * *
-* @param float $a Length of 1st side+* @param number $a Length of 1st side
 * @requires ($a >= 0) * @requires ($a >= 0)
-* @param float $b Length of 2nd side+* @param number $b Length of 2nd side
 * @requires ($b >= 0) * @requires ($b >= 0)
-* @param float $c Length of 3rd side+* @param number $c Length of 3rd side
 * @requires ($c >= 0) * @requires ($c >= 0)
 * @requires ($a <= ($b+$c)) * @requires ($a <= ($b+$c))
Line 72: Line 87:
 * @requires ($c <= ($a+$b)) * @requires ($c <= ($a+$b))
 * *
-* @return float The triangle area+* @return number The triangle area
 * @ensures ($> >= 0) * @ensures ($> >= 0)
 */ */
Line 94: Line 109:
  
 $area=triangleArea('foo',2,3); $area=triangleArea('foo',2,3);
- -> PHP Fatal error: triangleArea: DbC input type mismatch - $a should match 'float' (string(3) "foo") in xxx on line nn+ -> PHP Fatal error: triangleArea: DbC input type mismatch - $a should match 'number' (string(3) "foo") in xxx on line nn
  
 $area=triangleArea(10,2,3); $area=triangleArea(10,2,3);
Line 143: Line 158:
 /*-- Properties */ /*-- Properties */
  
-/** @var float $a,$b,$c Side lengths */+/** @var number Side lengths */
  
 private $a,$b,$c; private $a,$b,$c;
Line 149: Line 164:
 //--------- //---------
 /** /**
-* @param float $a Length of 1st side +* @param number $a Length of 1st side 
-* @param float $b Length of 2nd side +* @param number $b Length of 2nd side 
-* @param float $c Length of 3rd side+* @param number $c Length of 3rd side
 * *
 * No need to repeat constraints on values as they are checked by class invariants. * No need to repeat constraints on values as they are checked by class invariants.
Line 169: Line 184:
 * This function computes the area of a triangle using Heron's formula. * This function computes the area of a triangle using Heron's formula.
 * *
-* @return float The triangle area+* @return number The triangle area
 * @ensures ($> >= 0) * @ensures ($> >= 0)
 */ */
Line 191: Line 206:
  
 $t=new triangle('foo',2,3); $t=new triangle('foo',2,3);
- -> PHP Fatal error: triangle::__construct: DbC input type mismatch - $a should match 'float' (string(3) "foo") in xxx on line nn+ -> PHP Fatal error: triangle::__construct: DbC input type mismatch - $a should match 'number' (string(3) "foo") in xxx on line nn
  
 $area=triangleArea(10,2,3); $area=triangleArea(10,2,3);
Line 215: Line 230:
   * it allows to keep the source code executable on previous PHP interpreters.   * it allows to keep the source code executable on previous PHP interpreters.
   * Phpdoc comments, while not perfect, have always played the role of annotations in PHP. 'Real' annotations would be probably better but the don't exist yet. And they won't be approved in the near future. That's why everyone needing annotations so far has extended the phpdoc syntax.   * Phpdoc comments, while not perfect, have always played the role of annotations in PHP. 'Real' annotations would be probably better but the don't exist yet. And they won't be approved in the near future. That's why everyone needing annotations so far has extended the phpdoc syntax.
-  * DbC can use part of already-written phpdoc information (@param and @return types, @throws information too). So, unchanged code could already benefit of DbC.+  * DbC can use a great part of the already-written phpdoc informations (@param and @return types, @throws information too). So, unchanged code could already benefit of DbC.
  
 Note: Some people on the mailing list are religiously opposed to including information Note: Some people on the mailing list are religiously opposed to including information
Line 240: Line 255:
 seen as built-in conditions. seen as built-in conditions.
  
-Here are the main benefits of defining s set of DbC types :+Here are the main benefits of defining a set of DbC types :
  
   * PHP is_xxx() functions are not as intuitive as they may seem, as they are based on zval types (an equivalent of strict type checks). They are not appropriate for people who just want to accept a limited set of type juggling (accepting a numeric string from a DB, for instance). Unfortunately, checking that a given value is an integer or a string containing an integer is a common need, but is quite complex to write in PHP.   * PHP is_xxx() functions are not as intuitive as they may seem, as they are based on zval types (an equivalent of strict type checks). They are not appropriate for people who just want to accept a limited set of type juggling (accepting a numeric string from a DB, for instance). Unfortunately, checking that a given value is an integer or a string containing an integer is a common need, but is quite complex to write in PHP.
   * As it was already said, tons of source code already contains argument return/types in phpdoc. DbC types are designed to match as much as possible of this pre-existing information.   * As it was already said, tons of source code already contains argument return/types in phpdoc. DbC types are designed to match as much as possible of this pre-existing information.
   * Readability is a key point too: just compare a type like 'string|array(string|integer)' with the PHP code to check the same !   * Readability is a key point too: just compare a type like 'string|array(string|integer)' with the PHP code to check the same !
 +  * DbC types allow static analysis, which is practically impossible with conditions.
 +  * A lot of other analyzis/debugging/profiling tools can use this information.
  
 DbC types are used to check : DbC types are used to check :
Line 265: Line 282:
  
 type = "integer" type = "integer"
- | "float"+ | "integer!" 
 + | "number" 
 + | "float!"
  | "string"  | "string"
 + | "string!"
  | array-type  | array-type
  | "callable"  | "callable"
Line 275: Line 295:
  | "mixed"  | "mixed"
  | "boolean"  | "boolean"
 + | "boolean!"
  
 array-type = "array" array-type = "array"
Line 288: Line 309:
 === DbC types vs zval types === === DbC types vs zval types ===
  
-DbC types have specific rules to match PHP zvals. These rules are less permissive than+DbC types follow specific rules to match PHP zvals. These rules are less permissive than
 PHP API type juggling and previously-proposed scalar 'weak' typing, but more than previously-proposed strict typing. Actually, PHP API type juggling and previously-proposed scalar 'weak' typing, but more than previously-proposed strict typing. Actually,
 these types try to be a more intuitive compromise between both. these types try to be a more intuitive compromise between both.
Line 302: Line 323:
 ^ integer    |  No     |  Yes    |  (2)      |  No        |  No      |  No       |  (3)      |  No         | ^ integer    |  No     |  Yes    |  (2)      |  No        |  No      |  No       |  (3)      |  No         |
 ^ integer!   |  No     |  Yes    |  No       |  No        |  No      |  No       |  No       |  No         | ^ integer!   |  No     |  Yes    |  No       |  No        |  No      |  No       |  No       |  No         |
-^ float      |  No     |  Yes    |  Yes      |  No        |  No      |  No       |  (4)      |  No         |+^ number     |  No     |  Yes    |  Yes      |  No        |  No      |  No       |  (4)      |  No         |
 ^ float!     |  No     |  No     |  Yes      |  No        |  No      |  No       |  No       |  No         | ^ float!     |  No     |  No     |  Yes      |  No        |  No      |  No       |  No       |  No         |
 ^ string     |  No     |  Yes    |  Yes      |  No        |  No      |  (6)      |  Yes      |  No         | ^ string     |  No     |  Yes    |  Yes      |  No        |  No      |  (6)      |  Yes      |  No         |
 ^ string!    |  No     |  No     |  No       |  No        |  No      |  (6)      |  Yes      |  No         | ^ string!    |  No     |  No     |  No       |  No        |  No      |  (6)      |  Yes      |  No         |
 ^ array      |  No     |  No     |  No       |  No        |  Yes     |  No       |  No       |  No         | ^ array      |  No     |  No     |  No       |  No        |  Yes     |  No       |  No       |  No         |
-^ callable   |  No     |  No     |  No       |  No        |  (5)     |  No       |  (5)      |  No         |+^ callable   |  No     |  No     |  No       |  No        |  (5)     |  (5)      |  (5)      |  No         |
 ^ object     |  No     |  No     |  No       |  No        |  No      |  Yes      |  No       |  No         | ^ object     |  No     |  No     |  No       |  No        |  No      |  Yes      |  No       |  No         |
 ^ resource   |  No     |  No     |  No       |  No        |  No      |  No       |  No       |  Yes        | ^ resource   |  No     |  No     |  No       |  No        |  No      |  No       |  No       |  Yes        |
Line 323: Line 344:
   * (6) only if class defines a %%__%%toString() method\\   * (6) only if class defines a %%__%%toString() method\\
   * (7) O is false, 1 is true. Other values don't match (to be discussed)   * (7) O is false, 1 is true. Other values don't match (to be discussed)
- 
-You may note that this is much more restrictive that PHP native type juggling. 
  
 === DbC types === === DbC types ===
Line 345: Line 364:
 Synonyms: 'int!' Synonyms: 'int!'
  
-== float ==+== number ==
  
 Any value that returns true through is_numeric(). Any value that returns true through is_numeric().
Line 351: Line 370:
 Equivalent to 'is_numeric($arg)'. Equivalent to 'is_numeric($arg)'.
  
-Synonyms: 'numeric', 'number'+Synonyms: 'numeric', 'float'
  
 == float! == == float! ==
Line 385: Line 404:
 == callable == == callable ==
  
-A string or array returning true through 'is_callable($arg,true)'.+A string, object or array returning true through 'is_callable($arg,true)'.
  
 Please consult the [[http://php.net/manual/en/function.is-callable.php|is_callable() documentation]] for more details. Please consult the [[http://php.net/manual/en/function.is-callable.php|is_callable() documentation]] for more details.
Line 678: Line 697:
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
  
-PHP 7. Backporting to PHP 5 is possible if implemented as a separate extension.+As the plan is to implement this in a separate extension, it should be availbale for PHP 5 ans PHP 7.
  
 ===== RFC Impact ===== ===== RFC Impact =====
Line 735: Line 754:
  
 [[https://wiki.php.net/rfc/dbc2|Alternative RFC]] [[https://wiki.php.net/rfc/dbc2|Alternative RFC]]
- 
rfc/dbc.1423748616.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools