Skip to content

Assorted formatting and wording cleanup. #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 5, 2023
Merged

Assorted formatting and wording cleanup. #56

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ae9bb1
Assorted formatting and wording cleanup.
Crell Jan 13, 2023
c56f02b
Typo fixes
Crell Jan 14, 2023
7b098dc
Minor cleanup.
Crell Feb 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 54 additions & 47 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -293,15 +294,15 @@ 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();
```

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 {}
Expand All @@ -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
<?php
Expand All @@ -340,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.
one interface per line. For example:

```php
<?php
Expand All @@ -365,22 +364,11 @@ class ClassName extends ParentClass implements
The `use` keyword used inside the classes to implement traits MUST be
declared on the next line after the opening brace.

```php
<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName
{
use FirstTrait;
}
```

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 usage.

```php
<?php

Expand All @@ -400,6 +388,7 @@ class ClassName

When the class has nothing after the `use` import statement, the class
closing brace MUST be on the next line after the `use` import statement.
For example:

```php
<?php
Expand All @@ -414,7 +403,7 @@ class ClassName
}
```

Otherwise, it MUST have a blank line after the `use` import statement.
Otherwise, it MUST have a blank line after the `use` import statement, as in:

```php
<?php
Expand All @@ -431,7 +420,7 @@ class ClassName
}
```

When using the `insteadof` and `as` operators they must be used as follows taking
When using the `insteadof` and `as` operators they MUST be used as follows taking
note of indentation, spacing, and new lines.

```php
Expand Down Expand Up @@ -525,7 +514,7 @@ function fooBarBaz($arg1, &$arg2, $arg3 = [])

If a function or method contains no statements (such as a no-op implementation or when using
constructor property promotion), then the body SHOULD be abbreviated as `{}` and placed on the same
line as the previous symbol, separated by a space. For example:
line as the previous symbol, separated by a space. For example:

```php
class Point
Expand All @@ -552,7 +541,7 @@ In the argument list, there MUST NOT be a space before each comma, and there
MUST be one space after each comma.

Method and function parameters with default values MUST go at the end of the argument
list.
list. For example:

```php
<?php
Expand All @@ -574,7 +563,7 @@ next line, and there MUST be only one argument per line.

When the argument list is split across multiple lines, the closing parenthesis
and opening brace MUST be placed together on their own line with one space
between them.
between them. For example:

```php
<?php
Expand All @@ -596,7 +585,7 @@ class ClassName
When you have a return type declaration present, there MUST be one space after
the colon followed by the type declaration. The colon and declaration MUST be
on the same line as the argument list closing parenthesis with no spaces between
the two characters.
the two characters. For example:

```php
<?php
Expand All @@ -623,7 +612,7 @@ class ReturnTypeVariations
```

In nullable type declarations, there MUST NOT be a space between the question mark
and the type.
and the type. For example:

```php
<?php
Expand Down Expand Up @@ -667,7 +656,7 @@ public function process(string $algorithm, &...$parts)
### 4.6 Modifier Keywords

Classes, properties, and methods have numerous keyword modifiers that alter how the
engine and language handles them. When present, they MUST be in the following order:
engine and language handles them. When present, they MUST be in the following order:

* Inheritance modifier: `abstract` or `final`
* Visibility modifier: `public`, `protected`, or `private`
Expand All @@ -678,6 +667,8 @@ engine and language handles them. When present, they MUST be in the following o

All keywords MUST be on a single line, and MUST be separated by a single space.

The following is a correct example of modifier keyword usage:

```php
<?php

Expand Down Expand Up @@ -711,6 +702,8 @@ after the opening parenthesis, and there MUST NOT be a space before the
closing parenthesis. In the argument list, there MUST NOT be a space before
each comma, and there MUST be one space after each comma.

The following lines show correct calls:

```php
<?php

Expand All @@ -725,6 +718,8 @@ next line, and there MUST be only one argument per line. A single argument being
split across multiple lines (as might be the case with an anonymous function or
array) does not constitute splitting the argument list itself.

The following examples show correct argument usage.

```php
<?php

Expand All @@ -748,14 +743,14 @@ $app->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
Expand All @@ -768,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

Expand Down Expand Up @@ -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
<?php

Expand Down Expand Up @@ -867,6 +864,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
<?php

Expand Down Expand Up @@ -936,7 +935,7 @@ do {
Expressions in parentheses MAY be split across multiple lines, where each
subsequent line is indented at least once. When doing so, the first condition
MUST be on the next line. Boolean operators between conditions MUST
always be at the beginning or at the end of the line, not a mix of both.
always be at the beginning or at the end of the line, not a mix of both. For example:

```php
<?php
Expand Down Expand Up @@ -965,7 +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.
placed together on their own line with one space between them. For example:

```php
<?php
Expand Down Expand Up @@ -1023,7 +1022,7 @@ All operators not described here are left undefined.
### 6.1. Unary operators

The increment/decrement operators MUST NOT have any space between
the operator and operand.
the operator and operand:

```php
$i++;
Expand Down Expand Up @@ -1063,6 +1062,7 @@ $variable = $foo ? 'foo' : 'bar';

When the middle operand of the conditional operator is omitted, the operator
MUST follow the same style rules as other binary [comparison][] operators:

```php
$variable = $foo ?: 'bar';
```
Expand Down Expand Up @@ -1194,7 +1194,7 @@ The `=>` 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.
Expand Down Expand Up @@ -1231,7 +1231,7 @@ the list of `implements` interfaces does not wrap. If the list of interfaces
wraps, the brace MUST be placed on the line immediately following the last
interface.

If the anonymous class has no arguments, the `()` after `class` MUST be omitted.
If the anonymous class has no arguments, the `()` after `class` MUST be omitted. For example:

```php
<?php
Expand Down Expand Up @@ -1260,17 +1260,19 @@ $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.

The following example shows a typical valid Enum:

```php
enum Suit: string
{
Expand All @@ -1296,6 +1298,7 @@ indentation they are declared in.

The following is ***not allowed*** due to the heredoc beginning on a
different line than the context it's being declared in:

```php
$notAllowed =
<<<'COUNTEREXAMPLE'
Expand All @@ -1306,11 +1309,12 @@ $notAllowed =
COUNTEREXAMPLE;
```

Instead the heredoc MUST be declared on the same line as the variable
Instead, the heredoc MUST be declared on the same line as the variable
declaration it's being set against.

The follow is ***not allowed*** due to the scope indention not matching the scope the
heredoc is declared in:

```php
function notAllowed()
{
Expand All @@ -1328,6 +1332,7 @@ it's declared in.

The following is an example of both a heredoc and a nowdoc declared in a
compliant way:

```php
function allowed()
{
Expand Down Expand Up @@ -1383,6 +1388,8 @@ MUST be placed on the next line after the last value. There MUST NOT be more
than one value assignment per line. Value assignments MAY use a single line
or multiple lines.

The following example shows correct array usage:

```php
<?php

Expand Down Expand Up @@ -1421,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
Expand All @@ -1435,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.

Expand Down