diff --git a/meta.md b/meta.md index 4ee811a..b3c98f3 100644 --- a/meta.md +++ b/meta.md @@ -89,136 +89,17 @@ keywords will not always meet the criteria for minor release. For example, speci of spaces for indentation creates a new implicit requirement that projects must use one style consistently; this new burden on projects to reformat incoming contributions to their chosen style defines the change as major. -## 5. Approaches - -The overarching approach is to attempt to apply existing PSR-12 styling and rationale to -new functionality as opposed to establishing new conventions. - -### 5.1. Strict Types Declarations - -There was a discussion about whether strict types should be enforced in the standard -https://github.com/cs-extended/fig-standards/issues/7. All were in agreement we should only -use a MUST or MUST NOT statement and avoid the use of a SHOULD statement and nobody wanted -to say that strict types could not be declared. The discussion was whether it should be -considered a coding style item which should be covered or whether it was out of scope, and it -was decided to be out of scope of a coding style guide. - -### 5.2. Finally and Return Types Declaration Spacing - -Numerous options were suggested, and they can be seen -[here for return type declarations](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) or -[here for finally blocks](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-finallyblocks-php) -and the current implementation was chosen due to consistency with other parts of the standard. - -### 5.3. Enforcing short form for all type keywords - -PHP 7.0 introduced [scalar types declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) -which does not support long type aliases. Therefore, it makes sense to enforce primary short type forms to be used to -have uniform syntax and prevent possible confusion. - -### 5.4. Public Survey - -In order to settle things using data, survey was conducted and responses from 142 people -including 17 project representatives were gathered: - -#### 5.4.1. PHP-FIG Representative Results - -| Representative | Project | Compound namespaces with a depth of two or more MUST not be used | Header statement grouping and ordering | Declare statements must each be on their own line | Declare statements in PHP files containing markup | Declare statements have no spaces: `declare(strict_types=1);` | Block declare statement formatting | `new` keyword usage, parenthesis required |Return type declaration formatting |Use statement leading slashes disallowed | Block namespace declaration formatting | General operator spacing |Try, Catch, Finally formatting | Anonymous class declaration formatting | Keyword casing, only lower case | Type keywords, short form only | -| -------------- | ------- | ---------------------------------------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------------------------------- |------------------------------- |------------------------------------ | ----------------------------------- | ---------------------- |--------------------------- | ----------------------------------- | --------------------------- | -------------------------- | -| Alexander Makarov | Yii framework | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Korvin Szanto | concrete5 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Leo Feyer | Contao | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Larry Garfield | Drupal | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ❌ | ✓ | ✓ | -| André R. | eZ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Jan Schneider | Horde | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Karsten Dambekalns | Neos and Flow | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Andres Gutierrez | Phalcon | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Ryan Thompson | PyroCMS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Matteo Beccati | Revive Adserver | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | -| Damian Mooyman | SilverStripe | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Brian Retterer | Stormpath PHP SDK | ✓ | ✓ | ✓ | ❌ | ❌ | ✓ | ❌ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ❌ | ❌ | -| Matthew Weier O'Phinney | Zend Framework | ❌ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Jordi Boggiano | Composer | ❌ | ❌ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Ben Marks | Magento | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Chuck Burgess | PEAR | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| | **Totals**: |13/3|15/1|15/1|13/3|14/2|15/1|14/2|15/1|14/2|14/2|15/1|16/0|15/1|15/1|15/1| - -#### 5.4.2. General non-representative voters - -| Question | For | Against | Percentage For | -| -------- | --- | ------- | -------------- | -| Compound namespaces required depth | 114 | 12 | 89.47% | -| Header statement grouping and ordering | 113 | 13 | 88.5% | -| Declare statements must each be on their own line | 120 | 6 | 95% | -| Declare statements in PHP files containing markup | 119 | 7 | 94.12% | -| Declare statements have no spaces | 116 | 10 | 91.38% | -| Block declare statement formatting | 118 | 8 | 93.22% | -| `new` keyword usage, parenthesis required | 116 | 10 | 91.38% | -| Return type declaration formatting | 115 | 11 | 90.43% | -| Use statement leading slashes disallowed | 118 | 8 | 93.22% | -| Block namespace declaration formatting | 120 | 6 | 95% | -| General operator spacing | 123 | 3 | 97.56% | -| Try, Catch, Finally formatting | 124 | 2 | 98.39% | -| Anonymous class declaration formatting | 117 | 9 | 92.31% | -| Keyword casing, only lower case | 124 | 2 | 98.39% | -| Type keywords, short form only | 121 | 5 | 95.87% | - -### 5.5. Multiline Function Arguments Mixed With Multiline Return - -A potential readability issue [was raised on the mailing list](https://groups.google.com/d/msg/php-fig/ULSL4gqK8GY/cgDELuPOCQAJ). -We reviewed options for changes to the specification that could provide better readability and -the floated option was to require a blank line after the opening bracket of a function if the -arguments and the return are both multiline. Instead, it was pointed out that this specification -_already_ allows you to decide where you'd like to add blank lines, and so we will leave it to -the implementors to decide. - -## 6. Changelog - -Please note this changelog is not a verbose list of changes from PSR-12 and further but highlights the most -notable changes. It should be considered a new specification, and therefore you should read the -specification for a full understanding of its contents. - -### 6.1. New Statements - -* Lowercase for all keywords - Section 2.5 -* Short form for all type keywords - Section 2.5 -* Use statement grouping - Section 3 -* Use statement blocks - Section 3 -* Declare statement/Strict types declaration usage - Section 3 -* Parentheses are always required for class instantiation - Section 4 -* Typed properties - Section 4.3 -* Return type declarations - Section 4.5 -* Variadic and reference argument operators - Section 4.5 -* Type hints - Section 4.5 -* Add finally block - Section 5.6 -* Operators - Section 6 -* Unary operators - Section 6.1 -* Binary operators - Section 6.2 -* Ternary operators - Section 6.3 -* Anonymous classes - Section 8 - -### 6.2. Clarifications and Errata - -* Adjust 'methods' to 'methods and functions' in a number of instances - Throughout -* Adjust references to classes and interfaces to also include traits - Throughout -* StudlyCaps meaning clarified as PascalCase - Section 2.1 -* The last line should not be blank but contain an EOL character - Section 2.2 -* Blank lines may be added for readability except where explicitly forbidden within the PSR - Section 2.3 -* PSR-2 errata statement about multi-line arguments - Section 4 -* PSR-2 errata statement about extending multiple interfaces - Section 4 -* Forbid blank lines before/after closing/opening braces for classes - Section 4 - -## 7. People - -### 7.1. Editor: +## 5. People + +### 5.1. Editor: * Larry Garfield -### 7.2. Sponsor: +### 5.2. Sponsor: * Chris Tankersley -### 7.3. Working Group Members: +### 5.3. Working Group Members: * Alexander Makarov * Ken Guest @@ -237,6 +118,7 @@ specification for a full understanding of its contents. _**Note:** Order descending chronologically._ +* **[Migration Document: PER-CS v2.0 to v3.0](migration-3.0.md)** * **[Migration Document: PER-CS v1.0 to v2.0](migration-2.0.md)** * **PSR-12:** https://www.php-fig.org/psr/psr-12/ * **PSR-2:** https://www.php-fig.org/psr/psr-2/