rfc:property_type_hints

Differences

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

Link to this comparison view

Next revision		Previous revision
rfc:property_type_hints [2015/07/19 11:49] – created mindplayrfc:property_type_hints [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== PHP RFC: Property type-hints ====== ====== PHP RFC: Property type-hints ======
-  * Version: 0.1+  * Version: 1.0
   * Date: 2015-07-19   * Date: 2015-07-19
   * Author: Rasmus Schultz <rasmus@mindplay.dk>   * Author: Rasmus Schultz <rasmus@mindplay.dk>
   * Status: Draft   * Status: Draft
-  * First Published at: http://wiki.php.net/rfc/type_checked_properties+  * First Published at: http://wiki.php.net/rfc/property_type_hints
  
 ===== Introduction ===== ===== Introduction =====
Line 13: Line 13:
 The significance of type-checked properties is a given, as demonstrated by it's inclusion in Hack, as well as other recent scripting languages, including Typescript, Dart and ActionScript. The need for type-hinting is demonstrated by the widespread use of php-doc, and support for such type-hinting in modern PHP IDEs. The significance of type-checked properties is a given, as demonstrated by it's inclusion in Hack, as well as other recent scripting languages, including Typescript, Dart and ActionScript. The need for type-hinting is demonstrated by the widespread use of php-doc, and support for such type-hinting in modern PHP IDEs.
  
-The proposed syntax is compatible with that of Hack, and is a natural addition to the language, resembling the syntax set forth by plenty other gruadually-typed (and statically-typed) languages.+The proposed syntax is compatible with that of Hack, and is a natural addition to the language, resembling the syntax set forth by other gruadually-typed (and statically-typed) languages.
  
 ===== Proposal ===== ===== Proposal =====
Line 24: Line 24:
 </code> </code>
  
-This declares a public property $value which can only be initialized or set with an integer scalar value.+This declares a public property ''$value'', which can only be initialized or set with an integer value.
  
-Scalar type hints, as per the addition in PHP 7, are permitted, as well as any class or interface name.+Scalar type hints (e.g. int, float, bool, string as supported by PHP 7) are permitted, as well as any class or interface name. 
 + 
 +The precise behavior as far as type-checking and type-conversions is dependent on the [[https://wiki.php.net/rfc/scalar_type_hints_v5||strict_types]] directive - that is, the precise behavior when setting a property, is consistent with that of scalar type-hints in function parameters.
  
 Violating the type-check when initializing or setting a property, will result in a catchable fatal error: Violating the type-check when initializing or setting a property, will result in a catchable fatal error:
Line 37: Line 39:
  
 Consistent with return type-check violations, and scalar type-hinting, this example will generate an ''E_RECOVERABLE_ERROR''. Consistent with return type-check violations, and scalar type-hinting, this example will generate an ''E_RECOVERABLE_ERROR''.
 +
 +==== Property References ====
 +
 +Type-checking is performed even if the property is indirectly modified via a property-reference. For example:
 +
 +<code php>
 +$i = new BoxedInt();
 +$ref = &$i->value;
 +$ref = 'oops'; // Catchable fatal error
 +</code>
 +
 +This behavior guarantees the integrity of a type-checked property, even if modified indirectly.
 +
 +==== Property Initialization ====
 +
 +If a given property is initialized with a scalar value, the constant scalar expression will be type-checked at construction time. For example:
 +
 +<code php>
 +class BoxedInt {
 +    public int $value = 'zero'; // NOTE: does not generate an error at load-time
 +}
 +
 +$i = new BoxedInt(); // Catchable fatal error
 +</code>
 +
 +Note that, while some languages would generate a parse error for the declaration itself, such behavior would not be practical in PHP, where, for example, initialization with a scalar expression such as ''Foo::BAR'' would trigger immediate auto-loading of ''Foo'', which could have surprising performance implications.
 +
 +Also note that the proposed behavior is consistent with initialization of constants, in the sense that e.g. ''const FOO = Bar::BAZ'' will not evaluate at load-time (which would cause auto-loading of ''Bar'') but rather will initialize when first accessed. Similarly, property initializations will evaluate (with type-checking) when the ''new'' operator is used.
 +
 +==== ReflectionProperty ====
 +
 +[[http://php.net/manual/en/class.reflectionproperty.php|ReflectionProperty]] needs an addition (consistent with [[http://php.net/manual/en/class.reflectionparameter.php|ReflectionParameter]]) to reflect the type-hint, e.g.:
 +
 +<code php>
 +ReflectionParameter implements Reflector {
 +    ...
 +    public ReflectionType getType ( void )
 +    ...
 +}
 +</code>
 +
 +Note that type-checking (and/or scalar type-conversion, depending on the strict_mode directive) will also be performed if a property is modified via the [[http://php.net/manual/en/reflectionproperty.setvalue.php||ReflectionProperty::setValue()]] method.
 +
 +TBD: [[https://wiki.php.net/rfc/reflectionparameter.typehint|Another RFC]] is in the works, which could affect the Reflection API changes proposed by this RFC.
 +
 +===== Non-features =====
 +
 +The inclusion of a ''var'' keyword (to be used in place of a type-hint, which would infer the property type-hint from the initialization) was considered, but is not part of this RFC. As per the description of property initialization behavior above, the expression used for initialization of a property is not evaluated until the ''new'' keyword is applied - hence, explicit type-inference in this manner isn't possible, since the property type needs to be available for reflection immediately after loading, e.g. prior to creation of an instance.
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 47: Line 97:
 ==== To Opcache ==== ==== To Opcache ====
 The impact on opcache needs to be examined. The impact on opcache needs to be examined.
 +
 +==== To Zend Engine ====
 +Static type-hints could enable some engine optimizations - this should be investigated.
  
 ===== Open Issues ===== ===== Open Issues =====
-To be determined: documentation for existing, standard classes (reflection, spl, etc.) may need updates, e.g. adding type-hints to existing class documentation.+None
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
 The introduction of an optional type-hint does not affect legacy PHP code. The introduction of an optional type-hint does not affect legacy PHP code.
 +
 +To preserve backwards compatibility, existing standard library classes will not have property type-hints added to them.
  
 ===== Future Scope ===== ===== Future Scope =====
Line 70: Line 125:
  
 ===== References ===== ===== References =====
-TBD+None
  
 ===== Rejected Features ===== ===== Rejected Features =====
-TBD+None
  
rfc/property_type_hints.1437306566.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools