| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| rfc:var_type [2016/07/02 14:22] – Added prefix choice section fleshgrinder | rfc:var_type [2017/09/22 13:28] (current) – external edit 127.0.0.1 |
|---|
| ====== PHP RFC: var_type ====== | ====== PHP RFC: var_type ====== |
| * Version: 0.0 | * Version: 1.0 |
| * Date: 2016-06-25 | * Date: 2016-06-25 |
| * Author: Richard Fussenegger <php@fleshgrinder.com> | * Author: Richard Fussenegger <php@fleshgrinder.com> |
| * Status: Under Discussion | * Status: Declined |
| * First Published at: https://wiki.php.net/rfc/var_type | * First Published at: https://wiki.php.net/rfc/var_type |
| |
| There is still a default path in the C code that would result in the returned type being ''unknown''. This happens if none of the existing type checks available in C results in a positive check. In other words: this should never happen. The documentation above clearly states that this is actually an impossible situation, and encourages users to file a bug with a detailed description for us to account for it, if they manage to provoke such a situation. | There is still a default path in the C code that would result in the returned type being ''unknown''. This happens if none of the existing type checks available in C results in a positive check. In other words: this should never happen. The documentation above clearly states that this is actually an impossible situation, and encourages users to file a bug with a detailed description for us to account for it, if they manage to provoke such a situation. |
| |
| === Performance === | ==== Prefix Choice ==== |
| The new ''var_type()'' function is considerably faster than the old ''gettype()'' function because it is able to utilize globally cached interned strings for the type names since it uses the names that are in use everywhere. It would be a waste of resources to update ''gettype()'' to work in a similar manner because the type names it uses are not usable in other PHP contexts. For instance, ''double'' is an invalid type declarations, hence, caching it globally would only occupy memory for a single function. The same is true for ''boolean'' and ''integer''. | The function prefix ''var_'' was chosen on purpose because another possibly more suitable prefix like ''val_'' or ''value_'' would introduce a new prefix to the PHP ecosystem. It is true that this function can be used with the return value of functions too as well as with literal values, however, exactly the same argument is true for ''var_dump()'' and ''var_export()''. The goal of this RFC is it to improve consistency and not to introduce more inconsistencies. The assumption that the type of a variable is the type of its current value is furthermore logical and comprehensible. Last but not least, this function is probably not going to be used with literal values at all, since the type of them is definitely known to the developer writing the code. It might be used for return values of functions but the use cases seem very, very limited without storing the actual value to a variable first. |
| |
| <code php> | ==== Performance ==== |
| function d(double $d) {} | The new ''var_type()'' function is faster if full utilization of interned strings is possible because it can utilize globally cached strings for the type names. It makes no sense to optimize the old ''gettype()'' function in the same manner since caching of the old type names makes no sense, they are not useful in any other context and would occupy additional memory globally for a single function. |
| d(1.0); | |
| // Fatal error: Uncaught TypeError: Argument 1 passed to d() must be an instance of double, float given, ... | |
| |
| function b(boolean $b) {} | Note well that the various ''is_*'' functions are still faster and ''var_type()'' is not meant to compete with them, again, they serve different purposes. |
| b(true); | |
| // Fatal error: Uncaught TypeError: Argument 1 passed to b() must be an instance of boolean, boolean given, ... | |
| |
| function i(integer $i) {} | ==== Phasing Out of gettype ==== |
| i(1); | This RFC does **not** propose a deprecation of ''gettype()'' in PHP 7.x because it is a widely used function and there are currently no plans on how to deal with its counterpart ''settype()''. Even if there would be plans, a true deprecation of ''gettype()'' would be a bad idea in any context because libraries and applications need the ability to offer their users an upgrade path. This path would be very bumpy if PHP is emitting deprecation errors upon the usage of ''gettype()''. Such a library or application fallback might be necessary in situations like we see [[https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/DocParser.php#L756-L789|here it in Doctrine annotations]]. The solution for such situations would be something like: |
| // Fatal error: Uncaught TypeError: Argument 1 passed to i() must be an instance of integer, integer given, ... | |
| | <code php> |
| | if ((var_type($var) === $user_type || gettype($var) === $user_type) || $var instanceof $user_type) { |
| | // ... |
| | } |
| </code> | </code> |
| |
| ==== Prefix Choice ==== | However, a //soft deprecation// of ''gettype()'' is recommended, this means that the documentation page of ''gettype()'' will be updated with an informational box that recommends the usage of ''var_type()'' in favor of ''gettype()'' and any references to ''gettype()'' in the manual should be replaced with ''var_type()''. |
| The function prefix ''var_'' was chosen on purpose because another possibly more suitable prefix like ''val_'' or ''value_'' would introduce a new prefix to the PHP ecosystem. It is true that this function can be used with the return value of functions too as well as with literal values, however, exactly the same argument is true for ''var_dump()'' and ''var_export()''. The goal of this RFC is it to improve consistency and not to introduce more inconsistencies. The assumption that the type of a variable is the type of its current value is furthermore logical and comprehensible. Last but not least, this function is probably not going to be used with literal values at all, since the type of them is definitely known to the developer writing the code. It might be used for return values of functions but the use cases seem very, very limited without storing the actual value to a variable first. | |
| |
| ==== Phasing Out of gettype ==== | It is further recommended to tackle the deprecation and a possible removal of the ''gettype()'' function together with a proper solution for ''settype()'' in a future major release. A possible approach could be to emit an ''E_STRICT'' in PHP 8, deprecate in PHP 9, and remove in PHP 10; or any other combination that results in a long adoption period. |
| This RFC does **not** propose a deprecation of ''gettype()'' in PHP 7.x because it is a widely used function and there are currently no plans on how to deal with its counterpart ''settype()''. However, a //soft deprecation// of ''gettype()'' is recommended, this means that the documentation page of ''gettype()'' will be updated with an informational box that recommends the usage of ''var_type()'' in favor of ''gettype()'' and any references to ''gettype()'' in the manual should be replaced with ''var_type()''. | |
| |
| ===== Backward Incompatible Changes ===== | ===== Backward Incompatible Changes ===== |
| |
| ==== New Constants ==== | ==== New Constants ==== |
| The introduction of ''TYPE_*'' constants for the various data types of PHP is a logical additional extension to minimize magic strings in userland software an to avoid typos that might lead to bugs. That being said, the existence of these constants is not essential to this feature and has a separate voting poll. | The introduction of ''TYPE_*'' constants for the various data types of PHP is a logical additional extension to minimize magic strings in userland software an to avoid typos that might lead to bugs. That being said, the existence of these constants is not essential to this feature and has a separate voting poll. Note that the usage of the constants within an e.g. ''switch'' actually makes the code slower due to the additional look ups for these constants. Their usage is only of interest to remove magic strings from userland code and improve the design of software in general. |
| |
| <code php> | <code php> |
| */ | */ |
| const TYPE_CALLABLE = 'callable'; | const TYPE_CALLABLE = 'callable'; |
| |
| /** | |
| * Name of the regular scalar data type bool's negative value. | |
| * | |
| * @link https://secure.php.net/language.types.boolean | |
| */ | |
| const TYPE_FALSE = 'false'; | |
| |
| /** | /** |
| */ | */ |
| const TYPE_INT = 'int'; | const TYPE_INT = 'int'; |
| | |
| | /** |
| | * Name of the pseudo data type iterable. |
| | * |
| | * @link https://secure.php.net/language.types.iterable |
| | */ |
| | const TYPE_ITERABLE = 'iterable'; |
| |
| /** | /** |
| */ | */ |
| const TYPE_STRING = 'string'; | const TYPE_STRING = 'string'; |
| |
| /** | |
| * Name of the regular scalar data type bool's positive value. | |
| * | |
| * @link https://secure.php.net/language.types.boolean | |
| */ | |
| const TYPE_TRUE = 'true'; | |
| </code> | </code> |
| |
| ===== Proposed Voting Choices ===== | ===== Proposed Voting Choices ===== |
| This RFC will have two polls, one for the introduction of the ''var_type()'' function and one for the new ''TYPE_*'' constants in userland. Both require a 50%+1 majority to be accepted as they do not change the language's syntax. | This RFC will have two polls, one for the introduction of the ''var_type()'' function and one for the new ''TYPE_*'' constants in userland. Both require a 50%+1 majority to be accepted as they do not change the language's syntax. |
| | |
| | Voting opened on 2016-07-08 and will end on 2016-07-22 for both votes. |
| | |
| | == Function == |
| | <doodle title="Accept var_type function?" auth="fleshgrinder" voteType="single" closed="false"> |
| | * Yes |
| | * No |
| | </doodle> |
| | |
| | == Constants == |
| | <doodle title="Accept type constants?" auth="fleshgrinder" voteType="single" closed="true"> |
| | * Yes |
| | * No |
| | </doodle> |
| |
| ===== Patches and Tests ===== | ===== Patches and Tests ===== |
| The [[https://github.com/php/php-src/pull/1935|GitHub Pull Request #1935]] contains the implementation as well as tests for the new function. The changes in the PR are considered final, however, a thorough code review would be much appreciated and might result in minor changes. | The [[https://github.com/php/php-src/pull/1935|GitHub Pull Request #1935]] contains the implementation as well as tests for the new function. The changes in the PR are considered final, however, a thorough code review would be much appreciated and might result in minor changes. |
| |
| ===== Implementation ===== | |
| - Merged to Version: //?// | |
| - Git Commits: //?// | |
| - PHP Manual: https://secure.php.net/var_type | |
| |
| ===== References ===== | ===== References ===== |