From d02ffe55d113bd3db6618b166231340e9da59879 Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Wed, 21 Feb 2018 23:18:53 -0900 Subject: [PATCH 01/11] Add RFC for Type Declarations --- text/0000-type-declarations.md | 128 +++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 text/0000-type-declarations.md diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md new file mode 100644 index 0000000..f6c5cbb --- /dev/null +++ b/text/0000-type-declarations.md @@ -0,0 +1,128 @@ +- Start Date: 2018-02-21 +- RFC PR: +- WordPress Coding Standards Issue: + +# Summary + +[Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) make code more readable. They also protect code, because Type Declarations are a way of enforcing specific data types in parameters passed to a function. + +# Basic Example + +You can force callers to pass an `array`, or a specific type of object, such as a `WP_REST_Request`. If a caller doesn't pass the data type expected, PHP 5 triggers a recoverable fatal error and PHP 7 throws a [TypeError](http://php.net/manual/en/class.typeerror.php) exception. This behavior catches problems right away. + +```php +protected function foo( Bar $bar, array $items ) { + // $bar must be an instance of the Bar class. + // $items must be passed as an array. +} +``` + +# Motivation + +PHP is a [weakly typed language](https://en.wikipedia.org/wiki/Strong_and_weak_typing). It doesn't require you to declare data types. However, variables still have data types associated with them (e.g., `string`, `integer`). In a weakly typed language you can do radical things like adding a `string` to an `integer` with no error. While this can be wonderful in some cases, it can also lead to unanticipated behavior and bugs. + +For example, PHP functions and class methods accept parameters, such as `function foo( $bar, $items )`. If Type Declarations aren't being used, the only way a function knows what it's being passed is to run `is_*()` checks, `instanceof`, or use type casting. Otherwise, `$bar` could be anything, and there's a chance that invalid data types would go unnoticed (no error) and produce an unexpected or incorrect return value. Imagine type casting an array to an integer. That's forcing a wrong into a right, instead of correcting the underlying issue. A caller should pass the right data type to begin with. + +So Type Declarations are advantageous, because ultimately, they produce improved error messages that catch problems right away. In the same way we _discourage_ use of the `@` error control operator and _encourage_ strict comparison `===`, Type Declarations shine a light a bugs. They're a way of being more explicit about the expected data type. An added benefit is more readable code. + +# Detailed Design + +## Valid Type Declarations in PHP 5.1+ + +- Class or interface name; e.g., `WP_REST_Request` +- `self`, which references own class or interface name +- `array`, to require an array + +**Formatting:** There should be one space before and after a Type Declaration. + +```php +protected function foo( Bar $bar, array $items ) { + // $bar must be an instance of the Bar class. + // $items must be passed as an array. +} +``` + +## Modern Versions of PHP + +Other data types, such as `callable`, `string`, `int`, `float`, and `bool` [became available in PHP 7.0](http://php.net/manual/en/migration70.new-features.php). In addition, PHP 7.0 added support for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). Support for the `iterable` Type Declaration became available in PHP 7.1. + +**Formatting:** A Return Type Declaration should immediately follow a function's round closing bracket `)`, with no space before `:`, and with one space before and after the data type. + +```php +protected function foo( string $str, int $num, bool $flag, callable $callback ): bool { + // $str must be passed as a string. + // $num must be passed as an integer. + // $flag must be passed as true or false. + // $callback must be a callable function, method, closure. + + return true; // must return true or false. +} +``` + +## WordPress Core Compatibility + +At this time, the additional type declarations: `callable`, `string`, `int`, `float`, `bool`, and `iterable` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. + +## When to Use Type Declarations + +When you're writing a function or a class method that expects to receive an array or a specific object type, and there is no reason to accept anything other than that specific data type. + +```php +protected function foo( Bar $bar, array $items ) { + // $bar must be an instance of the Bar class. + // $items must be passed as an array. +} +``` + +## When Not to Use Type Declarations + +If the function you're writing is part of a public API and enforcing a specific data type would make the function less flexible in the eyes of a caller. For example, the [`get_post()`](https://developer.wordpress.org/reference/functions/get_post/) function in WordPress core accepts `int|WP_Post|null` as the first parameter. This maximizes flexibility for callers, making the function more convenient in a variety of circumstances. + +Likewise, if you're writing a public function for an API and it needs a `WP_Post` instance, it's better not to enforce `WP_Post` with a type declaration. Instead, use the `get_post()` function to resolve the `$post` reference, making it possible for a caller to pass `int|WP_Post|null` to your function as well. + +```php +function foo( $post ) { + $post = get_post( $post ); + ... +} +``` + +# Drawbacks + +## Runtime Errors + +Using Type Declarations can lead to recoverable fatal errors in PHP 5, and [TypeError](http://php.net/manual/en/class.typeerror.php) exceptions in PHP 7. This is both a blessing and a curse. Runtime errors are mostly advantageous for reasons already stated elsewhere in this RFC; i.e., they help catch bugs right away. + +However, unlike [`_doing_it_wrong()`](https://developer.wordpress.org/reference/functions/_doing_it_wrong/), errors associated with invalid data types are more difficult to suppress. Imagine a plugin author writing code that calls upon a core function. If the core function uses Type Declarations to enforce specific data types, and the plugin passes an invalid type, an HTTP error response or WSOD could occur. + +# Adoption Strategy + +Retrofitting existing functions with Type Declarations is generally discouraged. Doing so would suddenly enforce a rule that did not exist prior, causing runtime errors. For example, imagine themes and plugins calling core functions that previously accepted multiple data types, but now require a specific type. Not good! This scenario should be avoided. + +However, new functions (particularly protected and private methods of a class) are encouraged to use Type Declarations supported by the minimum version of PHP they are targeting. If targeting a modern version of PHP (7.0+), the use of [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) is encouraged also. + +# Teaching Strategy + +Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). For this reason, please use the up-to-date and official terminology: + +- [Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) +- [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) +- [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) (aka: Strict Mode) + +## Limitations in WordPress Core + +Given current minimum requirements in WordPress Core (PHP 5.2.4+), Return Type Declarations and Strict Typing should be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. + +The only Type Declarations supported in WordPress Core at this time, are: + +- Class or interface name; e.g., `WP_REST_Request` +- `self`, which references own class or interface name +- `array`, to require an array + +# Unresolved Questions + +- If sniffs are added for Type Declarations: + - Are there any circumstances in which Type Declarations **MUST** be used? + - Are there any circumstances in which Type Declarations **MUST NOT** be used? + +- Should steps be taken to suppress runtime errors caused by invalid data types when running in a production environment? If so, what options are available for consideration? From 3afd47050e88dc403e5f1e9297268e4943e81e8e Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Mon, 26 Feb 2018 19:54:32 -0900 Subject: [PATCH 02/11] Remove the word "radical"; too strong --- text/0000-type-declarations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index f6c5cbb..27fcf28 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -19,7 +19,7 @@ protected function foo( Bar $bar, array $items ) { # Motivation -PHP is a [weakly typed language](https://en.wikipedia.org/wiki/Strong_and_weak_typing). It doesn't require you to declare data types. However, variables still have data types associated with them (e.g., `string`, `integer`). In a weakly typed language you can do radical things like adding a `string` to an `integer` with no error. While this can be wonderful in some cases, it can also lead to unanticipated behavior and bugs. +PHP is a [weakly typed language](https://en.wikipedia.org/wiki/Strong_and_weak_typing). It doesn't require you to declare data types. However, variables still have data types associated with them (e.g., `string`, `integer`). In a weakly typed language you can do things like adding a `string` to an `integer` with no error. While this can be wonderful in some cases, it can also lead to unanticipated behavior and bugs. For example, PHP functions and class methods accept parameters, such as `function foo( $bar, $items )`. If Type Declarations aren't being used, the only way a function knows what it's being passed is to run `is_*()` checks, `instanceof`, or use type casting. Otherwise, `$bar` could be anything, and there's a chance that invalid data types would go unnoticed (no error) and produce an unexpected or incorrect return value. Imagine type casting an array to an integer. That's forcing a wrong into a right, instead of correcting the underlying issue. A caller should pass the right data type to begin with. From 1b0d98a753e2694674babd3ceaa75b732300fdae Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Mon, 26 Feb 2018 20:24:08 -0900 Subject: [PATCH 03/11] PHP version-specific corrections --- text/0000-type-declarations.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 27fcf28..9fdfe03 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -44,7 +44,10 @@ protected function foo( Bar $bar, array $items ) { ## Modern Versions of PHP -Other data types, such as `callable`, `string`, `int`, `float`, and `bool` [became available in PHP 7.0](http://php.net/manual/en/migration70.new-features.php). In addition, PHP 7.0 added support for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). Support for the `iterable` Type Declaration became available in PHP 7.1. +- The [`callable` Type Declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) became available in PHP 5.4. +- [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool` became available in PHP 7.0, along with support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) and [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations). +- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. +- The [`object` Type Declaration](http://php.net/manual/en/migration72.new-features.php#migration72.new-features.object-type) became available in PHP 7.2. **Formatting:** A Return Type Declaration should immediately follow a function's round closing bracket `)`, with no space before `:`, and with one space before and after the data type. @@ -61,7 +64,7 @@ protected function foo( string $str, int $num, bool $flag, callable $callback ): ## WordPress Core Compatibility -At this time, the additional type declarations: `callable`, `string`, `int`, `float`, `bool`, and `iterable` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. +At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. ## When to Use Type Declarations @@ -103,15 +106,16 @@ However, new functions (particularly protected and private methods of a class) a # Teaching Strategy -Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). For this reason, please use the up-to-date and official terminology: +Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: - [Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) - [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) - [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) (aka: Strict Mode) +- [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) ## Limitations in WordPress Core -Given current minimum requirements in WordPress Core (PHP 5.2.4+), Return Type Declarations and Strict Typing should be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. +Given current minimum requirements in WordPress Core (PHP 5.2.4+), the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) — these cannot be used in WordPress Core. The only Type Declarations supported in WordPress Core at this time, are: From 1d51c873740566d50be628abac27d2f20e090bc5 Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Mon, 26 Feb 2018 20:46:39 -0900 Subject: [PATCH 04/11] Add a more detailed Formatting section --- text/0000-type-declarations.md | 51 ++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 9fdfe03..c49da53 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -33,8 +33,6 @@ So Type Declarations are advantageous, because ultimately, they produce improved - `self`, which references own class or interface name - `array`, to require an array -**Formatting:** There should be one space before and after a Type Declaration. - ```php protected function foo( Bar $bar, array $items ) { // $bar must be an instance of the Bar class. @@ -49,19 +47,54 @@ protected function foo( Bar $bar, array $items ) { - The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. - The [`object` Type Declaration](http://php.net/manual/en/migration72.new-features.php#migration72.new-features.object-type) became available in PHP 7.2. -**Formatting:** A Return Type Declaration should immediately follow a function's round closing bracket `)`, with no space before `:`, and with one space before and after the data type. +## Formatting + +### Whitespace + +There should be one space before and after a Type Declaration. + +```php +protected function foo( Bar $bar, array $items ) { + // ... +} +``` + +#### Return Type Declarations + +A Return Type Declaration should immediately follow a function's round closing bracket `)`, with no space before `:`, and with one space before and after the data type. ```php -protected function foo( string $str, int $num, bool $flag, callable $callback ): bool { - // $str must be passed as a string. - // $num must be passed as an integer. - // $flag must be passed as true or false. - // $callback must be a callable function, method, closure. +protected function foo(): array { + // ... +} +``` + +### Expected CaSe - return true; // must return true or false. +The expected caSe of Type Declarations is lowercase (e.g., `array`), except for class and interface names, which should always follow the name as declared by the class or interface; e.g., `WP_REST_Request` + +```php +protected function foo( array $data, WP_REST_Request $request ) { + // ... } ``` +### Expected Names + +The following are valid Type Declarations: +_**Note:** Use `int`, not `integer`. Use `bool`, not `boolean`._ + +- Class or interface name; e.g., `WP_REST_Request` +- `self`, which references own class or interface name +- `array` +- `callable` +- `string` +- `int` +- `float` +- `bool` +- `iterable` +- `object` + ## WordPress Core Compatibility At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. From 3ca526973fc32bdbc17ad359b46b1a9c9bf59a29 Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Mon, 26 Feb 2018 21:33:29 -0900 Subject: [PATCH 05/11] Add PSR-12 compatibility note and verbiage --- text/0000-type-declarations.md | 42 ++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index c49da53..0ecbde5 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -44,14 +44,16 @@ protected function foo( Bar $bar, array $items ) { - The [`callable` Type Declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) became available in PHP 5.4. - [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool` became available in PHP 7.0, along with support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) and [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations). -- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. +- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. - The [`object` Type Declaration](http://php.net/manual/en/migration72.new-features.php#migration72.new-features.object-type) became available in PHP 7.2. ## Formatting +_**Note:** These formatting rules follow [PSR-12](https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#45-method-and-function-arguments) exactly, with one additional clarification: There MUST be one space before and after a Type Declaration; e.g., `( array $items`, not `(array $items` or `(array$items`._ + ### Whitespace -There should be one space before and after a Type Declaration. +There MUST be one space before and after a Type Declaration. ```php protected function foo( Bar $bar, array $items ) { @@ -59,9 +61,18 @@ protected function foo( Bar $bar, array $items ) { } ``` +**Nullable Type Declarations:** +There MUST NOT be a space between the question mark and the Type Declaration. + +```php +protected function foo( ?Bar $bar, ?array $items ) { + // ... +} +``` + #### Return Type Declarations -A Return Type Declaration should immediately follow a function's round closing bracket `)`, with no space before `:`, and with one space before and after the data type. +The colon and Type Declaration MUST be on the same line as a function's closing parentheses. There MUST NOT be spaces between the function's closing parentheses and colon. There MUST be one space after the colon, followed by the Type Declaration. There MUST be one space after the Type Declaration; i.e., before the function's opening curly bracket. ```php protected function foo(): array { @@ -69,9 +80,18 @@ protected function foo(): array { } ``` -### Expected CaSe +**Nullable Type Declarations:** +There MUST NOT be a space between the question mark and the Type Declaration. + +```php +protected function foo(): ?array { + // ... +} +``` + +### Required CaSe -The expected caSe of Type Declarations is lowercase (e.g., `array`), except for class and interface names, which should always follow the name as declared by the class or interface; e.g., `WP_REST_Request` +The caSe of Type Declarations MUST be lowercase (e.g., `array`), except for class and interface names, which MUST always follow the name as declared by the class or interface; e.g., `WP_REST_Request` ```php protected function foo( array $data, WP_REST_Request $request ) { @@ -79,11 +99,12 @@ protected function foo( array $data, WP_REST_Request $request ) { } ``` -### Expected Names +### Required Form -The following are valid Type Declarations: _**Note:** Use `int`, not `integer`. Use `bool`, not `boolean`._ +The following are valid Type Declarations: + - Class or interface name; e.g., `WP_REST_Request` - `self`, which references own class or interface name - `array` @@ -97,7 +118,7 @@ _**Note:** Use `int`, not `integer`. Use `bool`, not `boolean`._ ## WordPress Core Compatibility -At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. +At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. ## When to Use Type Declarations @@ -139,16 +160,17 @@ However, new functions (particularly protected and private methods of a class) a # Teaching Strategy -Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: +Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: - [Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) - [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) - [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) (aka: Strict Mode) +- [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types) - [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) ## Limitations in WordPress Core -Given current minimum requirements in WordPress Core (PHP 5.2.4+), the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) — these cannot be used in WordPress Core. +Given current minimum requirements in WordPress Core (PHP 5.2.4+), the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) — these cannot be used in WordPress Core. The only Type Declarations supported in WordPress Core at this time, are: From 780451b0b7a157aadbc194679b333d13b30d8ec3 Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Mon, 26 Feb 2018 23:05:53 -0900 Subject: [PATCH 06/11] Explain Strict Mode, add a bit of polish --- text/0000-type-declarations.md | 69 ++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 0ecbde5..8ba339a 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -19,9 +19,9 @@ protected function foo( Bar $bar, array $items ) { # Motivation -PHP is a [weakly typed language](https://en.wikipedia.org/wiki/Strong_and_weak_typing). It doesn't require you to declare data types. However, variables still have data types associated with them (e.g., `string`, `integer`). In a weakly typed language you can do things like adding a `string` to an `integer` with no error. While this can be wonderful in some cases, it can also lead to unanticipated behavior and bugs. +PHP is a [weakly typed language](https://en.wikipedia.org/wiki/Strong_and_weak_typing). It doesn't require you to declare data types. However, variables still have data types associated with them (e.g., `string`, `int`). In a weakly typed language you can do things like adding a `string` to an `int` with no error. While this can be wonderful in some cases, it can also lead to unanticipated behavior and bugs. -For example, PHP functions and class methods accept parameters, such as `function foo( $bar, $items )`. If Type Declarations aren't being used, the only way a function knows what it's being passed is to run `is_*()` checks, `instanceof`, or use type casting. Otherwise, `$bar` could be anything, and there's a chance that invalid data types would go unnoticed (no error) and produce an unexpected or incorrect return value. Imagine type casting an array to an integer. That's forcing a wrong into a right, instead of correcting the underlying issue. A caller should pass the right data type to begin with. +For example, PHP functions and class methods accept parameters, such as `function foo( $bar, $items )`. If Type Declarations aren't being used, the only way a function knows what it's being passed is to run `is_*()` checks, `instanceof`, or use type casting. Otherwise, `$bar` could be anything, and there's a chance that invalid data types would go unnoticed and produce an unexpected or incorrect return value. Imagine type casting an array to an integer. That's forcing a wrong into a right, instead of correcting the underlying issue. A caller should pass the right data type to begin with. So Type Declarations are advantageous, because ultimately, they produce improved error messages that catch problems right away. In the same way we _discourage_ use of the `@` error control operator and _encourage_ strict comparison `===`, Type Declarations shine a light a bugs. They're a way of being more explicit about the expected data type. An added benefit is more readable code. @@ -43,16 +43,17 @@ protected function foo( Bar $bar, array $items ) { ## Modern Versions of PHP - The [`callable` Type Declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) became available in PHP 5.4. -- [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool` became available in PHP 7.0, along with support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) and [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations). -- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. +- [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool` became available in PHP 7.0, along with support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). +- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. - The [`object` Type Declaration](http://php.net/manual/en/migration72.new-features.php#migration72.new-features.object-type) became available in PHP 7.2. ## Formatting -_**Note:** These formatting rules follow [PSR-12](https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#45-method-and-function-arguments) exactly, with one additional clarification: There MUST be one space before and after a Type Declaration; e.g., `( array $items`, not `(array $items` or `(array$items`._ +_**Note:** All of these formatting rules follow [PSR-12](https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md#45-method-and-function-arguments), with one additional clarification: There MUST be one space before and after a Type Declaration; e.g., `( array $items`, not `(array$items`._ ### Whitespace +**The additional PSR-12 clarification:** There MUST be one space before and after a Type Declaration. ```php @@ -61,7 +62,7 @@ protected function foo( Bar $bar, array $items ) { } ``` -**Nullable Type Declarations:** +**Nullable Types:** There MUST NOT be a space between the question mark and the Type Declaration. ```php @@ -72,7 +73,7 @@ protected function foo( ?Bar $bar, ?array $items ) { #### Return Type Declarations -The colon and Type Declaration MUST be on the same line as a function's closing parentheses. There MUST NOT be spaces between the function's closing parentheses and colon. There MUST be one space after the colon, followed by the Type Declaration. There MUST be one space after the Type Declaration; i.e., before the function's opening curly bracket. +The colon and Type Declaration MUST be on the same line as a function's closing parentheses. There MUST NOT be spaces between the function's closing parentheses and colon. There MUST be one space after the colon, followed by the Type Declaration. There MUST be one space after the Type Declaration, before the function's opening curly bracket. ```php protected function foo(): array { @@ -80,7 +81,7 @@ protected function foo(): array { } ``` -**Nullable Type Declarations:** +**Nullable Types:** There MUST NOT be a space between the question mark and the Type Declaration. ```php @@ -91,7 +92,7 @@ protected function foo(): ?array { ### Required CaSe -The caSe of Type Declarations MUST be lowercase (e.g., `array`), except for class and interface names, which MUST always follow the name as declared by the class or interface; e.g., `WP_REST_Request` +The caSe of Type Declarations MUST be lowercase (e.g., `array`), except for class and interface names, which MUST follow the name as declared by the class or interface; e.g., `WP_REST_Request` ```php protected function foo( array $data, WP_REST_Request $request ) { @@ -118,11 +119,19 @@ The following are valid Type Declarations: ## WordPress Core Compatibility -At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. +At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. + +The only Type Declarations supported in WordPress Core at this time, are: + +- Class or interface name; e.g., `WP_REST_Request` +- `self`, which references own class or interface name +- `array`, to require an array + +_These can only be used in function parameters, not as Return Type Declarations._ ## When to Use Type Declarations -When you're writing a function or a class method that expects to receive an array or a specific object type, and there is no reason to accept anything other than that specific data type. +When you're writing a function or a class method that expects to receive an array or a specific object type, and there is no reason to accept anything other than that specific type. ```php protected function foo( Bar $bar, array $items ) { @@ -160,23 +169,41 @@ However, new functions (particularly protected and private methods of a class) a # Teaching Strategy -Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: +Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: - [Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) -- [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) +- [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations) +- [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) - [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) (aka: Strict Mode) -- [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types) +- [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types) - [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) -## Limitations in WordPress Core +## Default Behavior & Strict Mode -Given current minimum requirements in WordPress Core (PHP 5.2.4+), the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided altogether, and only mentioned for the purpose of explaining why they cannot be used at this time. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations), [Nullable Type Declarations](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) — these cannot be used in WordPress Core. +[Strict Mode](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) is possible in PHP 7.0+. Strict Mode only impacts [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool`. This can be somewhat confusing, so it must be explained in some detail and the [official documentation](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) should be reviewed carefully. It's important to understand both the default behavior and also the impact Strict Mode has. -The only Type Declarations supported in WordPress Core at this time, are: +### Default Behavior -- Class or interface name; e.g., `WP_REST_Request` -- `self`, which references own class or interface name -- `array`, to require an array +By default, PHP will, if possible, coerce scalar values of the wrong type into the expected type. For example, a function that is given an `int` for a parameter that expects a `string` will get a variable of type `string`. The `int` is magically converted into the `string` expected by a Scalar Type Declaration. + +This is also true in scalar Return Type Declarations. By default, scalar return values will be coerced to the correct type if they are not already of that type. + +_**Implication:** Because Strict Mode only impacts Scalar Type Declarations, when an invalid type is passed to a function using a non-scalar Type Declaration, it always produces a recoverable fatal error in PHP 5, or a [TypeError](http://php.net/manual/en/class.typeerror.php) in PHP 7. This is the default behavior and it cannot be altered, because Strict Mode has no impact on non-scalar Type Declarations._ + +### Enabling Strict Mode + +Strict Mode can be enabled on a per-file basis using the `declare` directive: + +```php + Date: Tue, 27 Feb 2018 07:17:41 -0900 Subject: [PATCH 07/11] fix: Remove unecessary word: 'both' --- text/0000-type-declarations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 8ba339a..2e8ec03 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -199,7 +199,7 @@ Strict Mode can be enabled on a per-file basis using the `declare` directive: declare( strict_types=1 ); ``` -In Strict Mode, when both the function call and the function declaration are both in a strict-typed file, only a variable of the exact type of the Scalar Type Declaration will be accepted. Otherwise, a [TypeError](http://php.net/manual/en/class.typeerror.php) will be thrown. The only exception to this rule is that an `int` may be given to a function expecting a `float`. +In Strict Mode, when both the function call and the function declaration are in a strict-typed file, only a variable of the exact type of the Scalar Type Declaration will be accepted. Otherwise, a [TypeError](http://php.net/manual/en/class.typeerror.php) will be thrown. The only exception to this rule is that an `int` may be given to a function expecting a `float`. This is also true for Return Type Declarations. Whenever a function is defined in a strict-typed file, a scalar return value must be of the correct type, otherwise a [TypeError](http://php.net/manual/en/class.typeerror.php) will be thrown. From f07a4c31c9c44f736c33beaf4748f9a1cfcce96e Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Wed, 7 Mar 2018 03:52:18 -0900 Subject: [PATCH 08/11] =?UTF-8?q?`Void=20Function`=20=E2=86=92=20`void=20R?= =?UTF-8?q?eturn=20Type=20Declaration`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- text/0000-type-declarations.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 2e8ec03..07d7d3f 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -44,7 +44,7 @@ protected function foo( Bar $bar, array $items ) { - The [`callable` Type Declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) became available in PHP 5.4. - [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations): `string`, `int`, `float`, and `bool` became available in PHP 7.0, along with support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) and [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict). -- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. +- The [`iterable` Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.iterable-pseudo-type), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [`void` Return Type Declaration](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) became available in PHP 7.1. - The [`object` Type Declaration](http://php.net/manual/en/migration72.new-features.php#migration72.new-features.object-type) became available in PHP 7.2. ## Formatting @@ -119,7 +119,7 @@ The following are valid Type Declarations: ## WordPress Core Compatibility -At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. +At this time, the additional Type Declarations: `callable`, `string`, `int`, `float`, `bool`, `iterable`, and `object` must be avoided in WordPress Core. The same is true for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), and [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types). Please see [WordPress requirements](https://wordpress.org/about/requirements/) (PHP 5.2.4+) and [this table](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for further details. The only Type Declarations supported in WordPress Core at this time, are: @@ -169,14 +169,13 @@ However, new functions (particularly protected and private methods of a class) a # Teaching Strategy -Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types), and [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions). For this reason, please use the up-to-date and official terminology: +Type Declarations were once known as Type Hints in PHP 5. That name is no longer appropriate, because later versions of PHP added support for [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations), [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict), and [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types). For this reason, please use the up-to-date and official terminology: - [Type Declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) - [Scalar Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.scalar-type-declarations) - [Return Type Declarations](http://php.net/manual/en/migration70.new-features.php#migration70.new-features.return-type-declarations) - [Strict Typing](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.strict) (aka: Strict Mode) - [Nullable Types](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.nullable-types) -- [Void Functions](http://php.net/manual/en/migration71.new-features.php#migration71.new-features.void-functions) ## Default Behavior & Strict Mode From d264aa30b85bf546c0ae8ea76562183e572efd82 Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Wed, 7 Mar 2018 03:55:13 -0900 Subject: [PATCH 09/11] Use tabs in code samples --- text/0000-type-declarations.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 07d7d3f..9a6ccb9 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -12,8 +12,8 @@ You can force callers to pass an `array`, or a specific type of object, such as ```php protected function foo( Bar $bar, array $items ) { - // $bar must be an instance of the Bar class. - // $items must be passed as an array. + // $bar must be an instance of the Bar class. + // $items must be passed as an array. } ``` @@ -35,8 +35,8 @@ So Type Declarations are advantageous, because ultimately, they produce improved ```php protected function foo( Bar $bar, array $items ) { - // $bar must be an instance of the Bar class. - // $items must be passed as an array. + // $bar must be an instance of the Bar class. + // $items must be passed as an array. } ``` @@ -58,7 +58,7 @@ There MUST be one space before and after a Type Declaration. ```php protected function foo( Bar $bar, array $items ) { - // ... + // ... } ``` @@ -67,7 +67,7 @@ There MUST NOT be a space between the question mark and the Type Declaration. ```php protected function foo( ?Bar $bar, ?array $items ) { - // ... + // ... } ``` @@ -77,7 +77,7 @@ The colon and Type Declaration MUST be on the same line as a function's closing ```php protected function foo(): array { - // ... + // ... } ``` @@ -86,7 +86,7 @@ There MUST NOT be a space between the question mark and the Type Declaration. ```php protected function foo(): ?array { - // ... + // ... } ``` @@ -96,7 +96,7 @@ The caSe of Type Declarations MUST be lowercase (e.g., `array`), except for clas ```php protected function foo( array $data, WP_REST_Request $request ) { - // ... + // ... } ``` @@ -135,8 +135,8 @@ When you're writing a function or a class method that expects to receive an arra ```php protected function foo( Bar $bar, array $items ) { - // $bar must be an instance of the Bar class. - // $items must be passed as an array. + // $bar must be an instance of the Bar class. + // $items must be passed as an array. } ``` @@ -148,8 +148,8 @@ Likewise, if you're writing a public function for an API and it needs a `WP_Post ```php function foo( $post ) { - $post = get_post( $post ); - ... + $post = get_post( $post ); + ... } ``` From 4171f0a94ddc3627724670cf53fdf84282766dcb Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Wed, 7 Mar 2018 04:03:19 -0900 Subject: [PATCH 10/11] Add `parent` type declaration --- text/0000-type-declarations.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 9a6ccb9..9218e53 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -31,6 +31,7 @@ So Type Declarations are advantageous, because ultimately, they produce improved - Class or interface name; e.g., `WP_REST_Request` - `self`, which references own class or interface name +- `parent`, which references parent class or interface name - `array`, to require an array ```php @@ -53,7 +54,7 @@ _**Note:** All of these formatting rules follow [PSR-12](https://github.com/php- ### Whitespace -**The additional PSR-12 clarification:** +**The additional PSR-12 clarification:** There MUST be one space before and after a Type Declaration. ```php @@ -62,7 +63,7 @@ protected function foo( Bar $bar, array $items ) { } ``` -**Nullable Types:** +**Nullable Types:** There MUST NOT be a space between the question mark and the Type Declaration. ```php @@ -81,7 +82,7 @@ protected function foo(): array { } ``` -**Nullable Types:** +**Nullable Types:** There MUST NOT be a space between the question mark and the Type Declaration. ```php @@ -108,6 +109,7 @@ The following are valid Type Declarations: - Class or interface name; e.g., `WP_REST_Request` - `self`, which references own class or interface name +- `parent`, which references parent class or interface name - `array` - `callable` - `string` @@ -116,6 +118,7 @@ The following are valid Type Declarations: - `bool` - `iterable` - `object` +- `void`, as a Return Type Declaration ## WordPress Core Compatibility @@ -125,6 +128,7 @@ The only Type Declarations supported in WordPress Core at this time, are: - Class or interface name; e.g., `WP_REST_Request` - `self`, which references own class or interface name +- `parent`, which references parent class or interface name - `array`, to require an array _These can only be used in function parameters, not as Return Type Declarations._ From 2f8cbe380693cefbe7a465615886f7e830fe6b0d Mon Sep 17 00:00:00 2001 From: Jason Caldwell Date: Wed, 7 Mar 2018 04:05:19 -0900 Subject: [PATCH 11/11] Strengthen stance against retrofitting --- text/0000-type-declarations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-type-declarations.md b/text/0000-type-declarations.md index 9218e53..10e4252 100644 --- a/text/0000-type-declarations.md +++ b/text/0000-type-declarations.md @@ -167,7 +167,7 @@ However, unlike [`_doing_it_wrong()`](https://developer.wordpress.org/reference/ # Adoption Strategy -Retrofitting existing functions with Type Declarations is generally discouraged. Doing so would suddenly enforce a rule that did not exist prior, causing runtime errors. For example, imagine themes and plugins calling core functions that previously accepted multiple data types, but now require a specific type. Not good! This scenario should be avoided. +Retrofitting existing functions with Type Declarations should be avoided 💯. Doing so would suddenly enforce a rule that did not exist prior, causing runtime errors. For example, imagine themes and plugins calling core functions that previously accepted multiple data types, but now require a specific type. Not good! This scenario must be avoided. However, new functions (particularly protected and private methods of a class) are encouraged to use Type Declarations supported by the minimum version of PHP they are targeting. If targeting a modern version of PHP (7.0+), the use of [Return Type Declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) is encouraged also.