rfc:returntypehint2

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:returntypehint2 [2011/12/20 22:31] – [Introduction] fitchwhrfc:returntypehint2 [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 3: Line 3:
   * Date: 2011-12-13   * Date: 2011-12-13
   * Author: Will Fitch <will.fitch@gmail.com>   * Author: Will Fitch <will.fitch@gmail.com>
-  * Status: In Draft+  * Status: Withdrawn
  
  
Line 24: Line 24:
 === Using Existing PHP Standards === === Using Existing PHP Standards ===
  
-With the introduction to the new object model in PHP 5 came parameter type hinting.  Developers could define objects and arrays (as of version 5.1), forcing the caller to provide a precise type or face raising a catchable fatal error.  This eliminated the need for functions and methods to constantly contain blocks of code verifying a provided value is a specific type.  Moving this check to the Zend Engine not only made execution faster, but it also saved precious development time.  This approach inherently provides valuable documentation and establishes a higher level of confidence in code.+With the introduction to the new object model in PHP 5 came parameter type hinting.  Developers could define objectsarrays (as of version 5.1) and callable (as of version 5.4), forcing the caller to provide a precise type or face raising a catchable fatal error.  This eliminated the need for functions and methods to constantly contain blocks of code verifying a provided value is a specific type.  Moving this check to the Zend Engine not only made execution faster, but it also saved precious development time.  This approach inherently provides valuable documentation and establishes a higher level of confidence in code.
  
 This implementation of return type hinting follows the same approach.  This provides consistency that developers appreciate.  When and if type hinting allows for additional types, the change can be applied to both methods and parameters. This implementation of return type hinting follows the same approach.  This provides consistency that developers appreciate.  When and if type hinting allows for additional types, the change can be applied to both methods and parameters.
 +
 +=== Returning NULL ===
 +
 +By default, if you specify a return type hint, you **must** return that type.  However, a new keyword "nullable" has been added to bypass this requirement.  Much like the parameter type hinting, this provides developers with added flexibility, and allows developers using an API to easily identify and code for that situation.
  
 === Example Implementations === === Example Implementations ===
Line 56: Line 60:
     }     }
          
-    public array getNullValue()+    public callable getCallableString() 
 +    { 
 +        return 'strlen'; 
 +    } 
 +     
 +    // The nullable keyword allows you to return null  
 +    protected nullable ArrayObject getArrayObject()
     {     {
         return null;         return null;
 +    }
 +    
 +    private callable methodModsDontMatter()
 +    {
 +        return 'str_replace';
 +    }
 +    
 +    ArrayObject methodsDontNeedModsActually()
 +    {
 +        return new ArrayObject();
     }     }
 } }
Line 115: Line 135:
 === Reflection === === Reflection ===
  
-Reflection has a minor change in this patch.  A new method called "getReturnType" has been added to ReflectionMethod which returns one of the following values: "mixed", "array" or "{ClassName}" (the actual class' name).  +Reflection has a minor change in this patch.  A new method called "getReturnType" has been added to ReflectionMethod which returns one of the following values: "mixed", "array", "callable" or "{ClassName}" (the actual class' name).  
  
 ==== Functional Implementation ==== ==== Functional Implementation ====
Line 123: Line 143:
 === Parser === === Parser ===
  
-The language parser "Zend/zend_language_parser.y" has been modified to add an additional term called "method_return_type" The definition for this contains one token, T_ARRAY, and one term - fully_qualified_class_name.  The method_return_type was added to class_statement, just above "function".  +The language parser "Zend/zend_language_parser.y" has been modified to add an additional term called "method_return_type" The definition for this contains two tokens, T_CALLABLE, T_ARRAY, and one term - fully_qualified_class_name.  The method_return_type was added to class_statement, just above "function".  
  
 I separated the "function" and "method_return_type" definitions within class_statement for two reasons.  First, I didn't want to introduce any additional changes to the compiler function zend_do_begin_function_declaration.  Since all function and method declarations go through this today, I didn't want to add logic within this just to verify if a method has defined a type hint.  This would've ended up in multiple places throughout the function, so I thought it would be best to let the parser deal with this once.  I separated the "function" and "method_return_type" definitions within class_statement for two reasons.  First, I didn't want to introduce any additional changes to the compiler function zend_do_begin_function_declaration.  Since all function and method declarations go through this today, I didn't want to add logic within this just to verify if a method has defined a type hint.  This would've ended up in multiple places throughout the function, so I thought it would be best to let the parser deal with this once. 
Line 131: Line 151:
 === Compiler === === Compiler ===
  
-As previously stated, a new function "zend_do_begin_returntype_method_declaration" was added.  This function takes care of verifying whether an array or object is defined, allocating and resolving the class name and finishing the additional tasks which are required for all methods and functions.  This does contain some redundant code from zend_do_begin_function_declaration, but in time, this can be resolved.+As previously stated, a new function "zend_do_begin_returntype_method_declaration" was added.  This function takes care of verifying whether an array or object is defined, allocating and resolving the class name and finishing the additional tasks which are required for all methods and functions.  This does contain some redundant code from zend_do_begin_function_declaration, but in time, this can be resolved.
  
 I also modified zend_do_begin_function_declaration to declare the type hint as IS_UNUSED and nullify the class name.   I also modified zend_do_begin_function_declaration to declare the type hint as IS_UNUSED and nullify the class name.  
Line 149: Line 169:
 === Tests === === Tests ===
  
-A total of 20 tests were added to tests/classes/ All tests file names are prefixed with "method_returntype_" for easy identification.  The tests do the following:+A total of 21 tests were added to tests/classes/ All tests file names are prefixed with "method_returntype_" for easy identification.  The tests do the following:
  
   * Determine that non-namespaced and namespaced class name don't produce a syntax error   * Determine that non-namespaced and namespaced class name don't produce a syntax error
   * Determines if a catchable fatal error is raised when an array or object is defined and the following are returned: resource, object, string, integer or double.  There are referenced return counterparts for these as well.   * Determines if a catchable fatal error is raised when an array or object is defined and the following are returned: resource, object, string, integer or double.  There are referenced return counterparts for these as well.
   * Determine if an E_COMPILE_ERROR is raised when a class implements an interface that defines a method which returns both an array and object, but fails to correctly redefine.    * Determine if an E_COMPILE_ERROR is raised when a class implements an interface that defines a method which returns both an array and object, but fails to correctly redefine. 
 +  * Determines if a callable works
 +  * Determines if a callable is defined but not returned
  
  
 ===== Patch ===== ===== Patch =====
  
-Patch: http://www.willfitch.com/php/returntype.patch +The patch for this is now outdated and gone
- +
-Github: https://github.com/fitchwh/php-src (returntype branch)+
  
  
Line 167: Line 187:
 ===== Changelog ===== ===== Changelog =====
  
 +  - Updated to include "callable" as an accepted return type. Includes patch and documentation changes 
 +  - Updated to remove allowing NULL to be returned unconditionally when declaring return types 
 +  - Added a new patch which includes a "nullable" token for declaring a method may return null 
 +  - Updated the RFC to take "nullable" into account and replaced the old patch with the new functionality
  
rfc/returntypehint2.1324420284.txt.gz · Last modified: 2017/09/22 13:28 (external edit)