From 3ae9bb1161cdc1c43e9021092981f3ab872cf29c Mon Sep 17 00:00:00 2001 From: Larry Garfield Date: Fri, 13 Jan 2023 14:58:08 -0600 Subject: [PATCH 1/3] Assorted formatting and wording cleanup. --- spec.md | 78 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/spec.md b/spec.md index f5c590a..503985d 100644 --- a/spec.md +++ b/spec.md @@ -279,6 +279,7 @@ Declare statements MUST NOT contain any spaces and MUST be exactly `declare(stri Block declare statements are allowed and MUST be formatted as below. Note position of braces and spacing: + ```php declare(ticks=1) { // some code @@ -293,7 +294,7 @@ Any closing brace MUST NOT be followed by any comment or statement on the same line. When instantiating a new class, parentheses MUST always be present even when -there are no arguments passed to the constructor. +there are no arguments passed to the constructor. For example: ```php new Foo(); @@ -312,15 +313,13 @@ class MyException extends \RuntimeException {} The `extends` and `implements` keywords MUST be declared on the same line as the class name. -The opening brace for the class MUST go on its own line; the closing brace -for the class MUST go on the next line after the body. - -Opening braces MUST be on their own line and MUST NOT be preceded or followed -by a blank line. +The opening brace for the class MUST go on its own line, and MUST NOT be +preceded or followed by a blank line. -Closing braces MUST be on their own line and MUST NOT be preceded by a blank -line. +The closing brace for the class MUST go on its own line, immediately following +the last line of the class body, and MUST NOT be preceded by a blank line. +The following is a validly formatted class: ```php get('/hello/{name}', function ($name) use ($app) { ``` If using named arguments, there MUST NOT be a space between the argument name -and colon, and there MUST be a single space between the colon and the argument value. +and colon, and there MUST be a single space between the colon and the argument value. For example: ```php somefunction($a, b: $b, c: 'c'); ``` Method chaining MAY be put on separate lines, where each subsequent line is indented once. When doing so, the first -method MUST be on the next line. +method MUST be on the next line. For example: ```php $someInstance @@ -815,6 +810,8 @@ placed together on their own line with one space between them. Boolean operators between conditions MUST always be at the beginning or at the end of the line, not a mix of both. +For example: + ```php Date: Sat, 14 Jan 2023 09:37:42 -0600 Subject: [PATCH 2/3] Typo fixes Co-authored-by: Alexander Makarov Co-authored-by: Theodore Brown --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 503985d..0cf2c21 100644 --- a/spec.md +++ b/spec.md @@ -367,7 +367,7 @@ declared on the next line after the opening brace. Each individual trait that is imported into a class MUST be included one-per-line and each inclusion MUST have its own `use` import statement. -The following is a correct example of trait `use`age. +The following is a correct example of trait usage. ```php Date: Sun, 5 Feb 2023 11:43:37 -0600 Subject: [PATCH 3/3] Minor cleanup. --- spec.md | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/spec.md b/spec.md index 0cf2c21..f677e76 100644 --- a/spec.md +++ b/spec.md @@ -131,7 +131,7 @@ Short form of type keywords MUST be used i.e. `bool` instead of `boolean`, ### 2.6 Trailing commas Numerous PHP constructs allow a sequence of values to be separated by a comma, -and the final item may have an optional comma. Examples include array key/value pairs, +and the final item may have an optional comma. Examples include array key/value pairs, function arguments, closure `use` statements, `match()` statement branches, etc. If that list is contained on a single line, then the last item MUST NOT have a trailing comma. @@ -294,7 +294,7 @@ Any closing brace MUST NOT be followed by any comment or statement on the same line. When instantiating a new class, parentheses MUST always be present even when -there are no arguments passed to the constructor. For example: +there are no arguments passed to the constructor. For example: ```php new Foo(); @@ -302,7 +302,7 @@ new Foo(); If class contains no additional declarations (such as an exception that exists only extend another exception with a new type), then the body of the class SHOULD be abbreviated as `{}` and placed on the same line as the previous symbol, -separated by a space. For example: +separated by a space. For example: ```php class MyException extends \RuntimeException {} @@ -339,7 +339,7 @@ class ClassName extends ParentClass implements \ArrayAccess, \Countable Lists of `implements` and, in the case of interfaces, `extends` MAY be split across multiple lines, where each subsequent line is indented once. When doing so, the first item in the list MUST be on the next line, and there MUST be only -one interface per line. For example: +one interface per line. For example: ```php get('/hello/{name}', function ($name) use ($app) { ``` If using named arguments, there MUST NOT be a space between the argument name -and colon, and there MUST be a single space between the colon and the argument value. For example: +and colon, and there MUST be a single space between the colon and the argument value. For example: ```php somefunction($a, b: $b, c: 'c'); ``` Method chaining MAY be put on separate lines, where each subsequent line is indented once. When doing so, the first -method MUST be on the next line. For example: +method MUST be on the next line. For example: ```php $someInstance @@ -763,7 +763,7 @@ $someInstance A function or method may be referenced in a way that creates a closure out of it, by providing `...` in place of arguments. -If so, the `...` MUST NOT include any whitespace before or after. That is, the correct format is `foo(...)`. +If so, the `...` MUST NOT include any whitespace before or after. That is, the correct format is `foo(...)`. ## 5. Control Structures @@ -964,8 +964,7 @@ for ($i = 0; $i < 10; $i++) { Expressions in parentheses MAY be split across multiple lines, where each subsequent line is indented at least once. When doing so, the first expression MUST be on the next line. The closing parenthesis and opening brace MUST be -placed together on their own line with one space between them. The semicolons -MUST be on the component they follow, not on the subsequent line. For example: +placed together on their own line with one space between them. For example: ```php ` symbol MUST be preceded and succeeded by a space. The semicolon at the end of the expression MUST NOT be preceded by a space. -The expression portion MAY be split to a subsequent line. If so, the `=>` MUST be included +The expression portion MAY be split to a subsequent line. If so, the `=>` MUST be included on the second line, and MUST be indented once. The following examples show proper common usage of short closures. @@ -1261,13 +1260,13 @@ $instance = new class($a) extends \Foo implements Enumerations (enums) MUST follow the same guidelines as classes, except where otherwise noted below. -Methods in enums MUST follow the same guidelines as methods in classes. Non-public methods MUST use `private` +Methods in enums MUST follow the same guidelines as methods in classes. Non-public methods MUST use `private` instead of `protected`, as enums do not support inheritance. When using a backed enum, there MUST NOT be a space between the enum name and colon, and there MUST be exactly one -space between the colon and the backing type. This is consistent with the style for return types. +space between the colon and the backing type. This is consistent with the style for return types. -Enum case declarations MUST use PascalCase capitalization. Enum case declarations MUST be on their own line. +Enum case declarations MUST use PascalCase capitalization. Enum case declarations MUST be on their own line. Constants in Enumerations MAY use either PascalCase or UPPER_CASE capitalization. PascalCase is RECOMMENDED, so that it is consistent with case declarations. @@ -1429,12 +1428,12 @@ be placed on their own line, immediately prior to the structure being described. For attributes on parameters, if the parameter list is presented on a single line, the attribute MUST be placed inline with the parameter it describes, separated by a single space. If the parameter list is split into multiple lines for any reason, the attribute MUST be placed on -its own line prior to the parameter, indented the same as the parameter. If the parameter list +its own line prior to the parameter, indented the same as the parameter. If the parameter list is split into multiple lines, a blank line MAY be included between one parameter and the attributes of the following parameter in order to aid readability. If a comment docblock is present on a structure that also includes an attribute, the comment block MUST -come first, followed by any attributes, followed by the structure itself. There MUST NOT be any blank lines +come first, followed by any attributes, followed by the structure itself. There MUST NOT be any blank lines between the docblock and attributes, or the attributes and the structure. If two separate attribute blocks are used in a multi-line context, they MUST be on separate lines with no blank @@ -1443,7 +1442,7 @@ lines between them. ### 12.3 Compound attributes If multiple attributes are placed in the same attribute block, they MUST be separated by a comma with a space -following but no space preceding. If the attribute list is split into multiple lines for any reason, then the +following but no space preceding. If the attribute list is split into multiple lines for any reason, then the attributes MUST be placed in separate attribute blocks. Those blocks may themselves contain multiple attributes provided this rule is respected.