From 1e09d7cde46402957db03a1eb55c3c59530a5c51 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:21:16 +0100 Subject: [PATCH 01/11] Update example at the beginning of PSR-12 to include strict types declaration, return type declaration and type hints. Also require new reserved words to be lowercase. --- proposed/extended-coding-style-guide.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index fcced37ee..2ea9805e9 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -35,6 +35,8 @@ This example encompasses some of the rules below as a quick overview: ```php $value) { } ``` -### 5.6. `try`, `catch` +### `try`, `catch` A `try catch` block looks like the following. Note the placement of parentheses, spaces, and braces. @@ -612,3 +611,4 @@ $instance = new class extends \Foo implements [PSR-1]: http://www.php-fig.org/psr/psr-1/ [PSR-2]: http://www.php-fig.org/psr/psr-2/ +[keywords]: http://php.net/manual/en/reserved.keywords.php \ No newline at end of file From d1c97636d4c7bb25d396afb9838bc37ac74ff31c Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:49:07 +0100 Subject: [PATCH 02/11] Add new rules for use statements and declaring strict types --- proposed/extended-coding-style-guide.md | 90 ++++++++++++++++++++----- 1 file changed, 75 insertions(+), 15 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 2ea9805e9..174f666ed 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -29,6 +29,11 @@ open to interpretation. This PSR therefore seeks to clarify the content of PSR-2 a more modern context with new functionality available, and make the errata to PSR-2 binding. +### Overview + +Throughout this document, any instructions MAY be ignored if they do not exist in versions +of PHP supported by your project. + ### Example This example encompasses some of the rules below as a quick overview: @@ -39,13 +44,15 @@ declare(strict_types=1); namespace Vendor\Package; -use FooInterface; -use BarClass as Bar; -use OtherVendor\OtherPackage\BazClass; +use Vendor\Package\{ClassA as A, ClassB, ClassC as C}; +use Vendor\Package\Namespace\ClassD as D; + +use function Vendor\Package\{func_a, func_b, func_c}; +use const Vendor\Package\{ConstantA, ConstantB, ConstantC}; class Foo extends Bar implements FooInterface { - public function sampleFunction(string $a, int $b = null): array + public function sampleFunction(int $a, int $b = null): array { if ($a === $b) { bar(); @@ -99,11 +106,6 @@ There MUST NOT be more than one statement per line. Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting. -> N.b.: Using only spaces, and not mixing spaces with tabs, helps to avoid -> problems with diffs, patches, history, and annotations. The use of spaces -> also makes it easy to insert fine-grained sub-indentation for inter-line -> alignment. - ### Keywords and True/False/Null PHP [keywords] MUST be in lower case. @@ -111,8 +113,10 @@ PHP [keywords] MUST be in lower case. The PHP reserved words `int`, `true`, `object`, `float`, `false`, `mixed`, `bool`, `null`, `numeric`, `string` and `resource MUST be in lower case -Namespace and Use Declarations ---------------------------------- +Namespace, Strict Types and Use Declarations +-------------------------------------------- + +When present, there MUST be one blank line before the `namespace` declaration. When present, there MUST be one blank line after the `namespace` declaration. @@ -121,22 +125,78 @@ declaration. There MUST be one `use` keyword per declaration. -There MUST be one blank line after the `use` block. +When using multiple classes, functions or constants within one namespace, you +MUST group use statements within one namespace. + +Use statements MUST be in a block according to the entity (class, function or group) +which is being grouped. Within each block there MUST be no blank lines. If a block +has multiple lines there MUST be a blank line before the first line and a blank line +after the last line. + +Classes, functions or constants grouped together into a single line must be listed +alphabetically. + +The groups MUST be ordered such that classes are first, followed by functions and +then constants. For example: ```php + + + + + +``` + 4. Classes, Properties, and Methods ----------------------------------- From 7680c68260c2c6ca7361d24df4fd733d831e5451 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:49:39 +0100 Subject: [PATCH 03/11] Be careful to use spaces and not tabs --- proposed/extended-coding-style-guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 174f666ed..e49f0df0f 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -156,7 +156,7 @@ use const Vendor\Package\{ConstantA, ConstantB, ConstantC}; class FooBar { - // ... additional PHP code ... + // ... additional PHP code ... } ``` @@ -190,9 +190,9 @@ For example: - + ``` From dc6dba8dd9599e39cc848ca4f764e387c3af817c Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:50:34 +0100 Subject: [PATCH 04/11] Clarify that the all files must end with a line containing only a LF character, not a blank line --- proposed/extended-coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index e49f0df0f..9356a99b1 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -81,7 +81,7 @@ Code MUST follow all rules outlined in [PSR-1]. All PHP files MUST use the Unix LF (linefeed) line ending. -All PHP files MUST end with a single blank line. +All PHP files MUST end with a single containing only a single newline (LF) character. The closing `?>` tag MUST be omitted from files containing only PHP. From e1668c3967d7e267996fb8a71d4873af64db9b22 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:51:38 +0100 Subject: [PATCH 05/11] Add further clarification that this does not overide explict instructions in the rest of the PSR --- proposed/extended-coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 9356a99b1..d64a8114e 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -98,7 +98,7 @@ be split into multiple subsequent lines of no more than 80 characters each. There MUST NOT be trailing whitespace at the end of non-blank lines. Blank lines MAY be added to improve readability and to indicate related -blocks of code. +blocks of code except where explictly forbidden. There MUST NOT be more than one statement per line. From c9fc7fb6c3caef63c7863796a2e097770208ec13 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 02:56:26 +0100 Subject: [PATCH 06/11] Fix references to methods to also reference functions --- proposed/extended-coding-style-guide.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index d64a8114e..4b25ffbfd 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -161,7 +161,6 @@ class FooBar ``` - All files MUST declare strict types. Files containing only PHP MUST contain the strict type declarations on the @@ -269,14 +268,14 @@ class ClassName } ``` -### Methods +### Methods and Functions Visibility MUST be declared on all methods. Method names SHOULD NOT be prefixed with a single underscore to indicate protected or private visibility. -Method names MUST NOT be declared with a space after the method name. The +Method and Function names MUST NOT be declared with a space after the method name. The opening brace MUST go on its own line, and the closing brace MUST go on the next line following the body. There MUST NOT be a space after the opening parenthesis, and there MUST NOT be a space before the closing parenthesis. @@ -295,14 +294,26 @@ class ClassName // method body } } -``` +``` + +A function declaration looks like the following. Note the placement of +parentheses, commas, spaces, and braces: + +```php + Date: Mon, 12 Oct 2015 03:11:30 +0100 Subject: [PATCH 07/11] Remove dated PSR-2 reference --- proposed/extended-coding-style-guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 4b25ffbfd..cd848cca5 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -645,8 +645,8 @@ $foo->bar( Anonymous Classes -------------------- -Anonymous Classes MUST be [PSR-2][] section 4 compatible barring the following -exceptions. +Anonymous Classes MUST follow the same guidelines and principles as closures +in the above section. ``` @@ -682,4 +682,4 @@ $instance = new class extends \Foo implements [PSR-1]: http://www.php-fig.org/psr/psr-1/ [PSR-2]: http://www.php-fig.org/psr/psr-2/ -[keywords]: http://php.net/manual/en/reserved.keywords.php \ No newline at end of file +[keywords]: http://php.net/manual/en/reserved.keywords.php From acf7ceec47cd1d3c9965b6b7d36dbd70abd3ec42 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 17:44:32 +0100 Subject: [PATCH 08/11] Adjust case for functions in use statements --- proposed/extended-coding-style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index cd848cca5..24170ee90 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -47,7 +47,7 @@ namespace Vendor\Package; use Vendor\Package\{ClassA as A, ClassB, ClassC as C}; use Vendor\Package\Namespace\ClassD as D; -use function Vendor\Package\{func_a, func_b, func_c}; +use function Vendor\Package\{functionA, functionB, functionC}; use const Vendor\Package\{ConstantA, ConstantB, ConstantC}; class Foo extends Bar implements FooInterface @@ -151,7 +151,7 @@ use Vendor\Package\{ClassA as A, ClassB, ClassC as C}; use Vendor\Package\Namespace\ClassD as D; use Vendor\Package\AnotherNamespace\ClassE as E; -use function Vendor\Package\{func_a, func_b, func_c}; +use function Vendor\Package\{functionA, functionB, functionC}; use const Vendor\Package\{ConstantA, ConstantB, ConstantC}; class FooBar From 0a962429eed803d209f156ae4eb3fea47eb48e7a Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 17:54:52 +0100 Subject: [PATCH 09/11] Ammend the line about use statement entity blocks to be clearer although still not perfect --- proposed/extended-coding-style-guide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 24170ee90..7264b7164 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -111,7 +111,7 @@ Code MUST use an indent of 4 spaces, and MUST NOT use tabs for indenting. PHP [keywords] MUST be in lower case. The PHP reserved words `int`, `true`, `object`, `float`, `false`, `mixed`, -`bool`, `null`, `numeric`, `string` and `resource MUST be in lower case +`bool`, `null`, `numeric`, `string` and `resource` MUST be in lower case Namespace, Strict Types and Use Declarations -------------------------------------------- @@ -128,18 +128,18 @@ There MUST be one `use` keyword per declaration. When using multiple classes, functions or constants within one namespace, you MUST group use statements within one namespace. -Use statements MUST be in a block according to the entity (class, function or group) -which is being grouped. Within each block there MUST be no blank lines. If a block -has multiple lines there MUST be a blank line before the first line and a blank line -after the last line. +Use statements MUST be in blocks, grouped by varying entity (classes [inc. interfaces], +functions or constants). Within each block there MUST be no blank lines. If a block has +multiple lines there MUST be a blank line before the first line and a blank line after +the last line. Classes, functions or constants grouped together into a single line must be listed alphabetically. -The groups MUST be ordered such that classes are first, followed by functions and -then constants. +The groups MUST be ordered such that classes (together with interfaces) are first, +followed by functions and then constants. -For example: +Example of the above notices about namespace, strict types and use declarations: ```php Date: Mon, 12 Oct 2015 18:33:39 +0100 Subject: [PATCH 10/11] Add commas where appropriate --- proposed/extended-coding-style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 7264b7164..433a82c9f 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -180,8 +180,8 @@ namespace Vendor\Package; ``` -Files containing HTML outside PHP opening and closing tags MUST on the first -line include an opening php tag, the strict types declaration and closing +Files containing HTML outside PHP opening and closing tags MUST, on the first +line, include an opening php tag, the strict types declaration and closing tag. For example: From ccd3a658c95ecb76aee9f3a507f965e0650e8a61 Mon Sep 17 00:00:00 2001 From: MichaelC Date: Mon, 12 Oct 2015 18:36:57 +0100 Subject: [PATCH 11/11] Attempt to explain better the grouping of use statements --- proposed/extended-coding-style-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposed/extended-coding-style-guide.md b/proposed/extended-coding-style-guide.md index 433a82c9f..208555198 100644 --- a/proposed/extended-coding-style-guide.md +++ b/proposed/extended-coding-style-guide.md @@ -129,7 +129,9 @@ When using multiple classes, functions or constants within one namespace, you MUST group use statements within one namespace. Use statements MUST be in blocks, grouped by varying entity (classes [inc. interfaces], -functions or constants). Within each block there MUST be no blank lines. If a block has +functions or constants). To elaborate, this means that any and all classes are in a block +together; any and all functions are in a block together; and any and all constants must +be grouped together. Within each block there MUST be no blank lines. If a block has multiple lines there MUST be a blank line before the first line and a blank line after the last line.