Skip to content

Commit 8201676

Browse files
samdarksamdark
authored
Add PSR-12 as is
1 parent 36f0afe commit 8201676

File tree

3 files changed

+1304
-1
lines changed

3 files changed

+1304
-1
lines changed

‎README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
1-
# PRE DRAFT repository for a coding style PER
1+
# PER coding style
2+
3+
- [Specification](spec.md)
4+
- [Meta Document](meta.md)

‎meta.md

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
Extended Coding Style Guide Meta Document
2+
=========================================
3+
4+
# 1. Summary
5+
6+
This document describes the process and discussions that led to the Extended Coding
7+
Style PSR. Its goal is to explain the reasons behind each decision.
8+
9+
# 2. Why Bother?
10+
11+
PSR-2 was accepted in 2012 and since then a number of changes have been made to PHP,
12+
most notably recent changes for PHP 7, which have implications for coding style
13+
guidelines. Whilst PSR-2 is very comprehensive of PHP functionality that existed at
14+
the time of writing, new functionality is very open to interpretation. PSR-12 seeks
15+
to provide a set way that both coding style tools can implement, projects can declare
16+
adherence to and developers can easily relate on between different projects for these
17+
coding style reducing cognitive friction.
18+
19+
PSR-2 was created based upon the common practices of the PHP-FIG projects at the time
20+
but ultimately this meant it was a compromise of many of the different projects' guidelines.
21+
The repercussions of projects changing their coding guidelines to align with PSR-2 (Almost
22+
all projects do align with PSR-1, even if it is not explicitly stated) were seen to be too
23+
great (losing git history, huge changesets and breaking existing patches/pull requests).
24+
25+
PSR-2 required adopters to reformat large amounts of existing code which stifled adoption.
26+
To help alleviate this issue with PSR-12, we have taken a more prescriptive approach and
27+
defined the standards for new language features as they are released.
28+
29+
However it is for a lack of wanting to be dictatorial that we will aim to apply PSR-2
30+
styling, rationale and stances (Described in Section 4, Approaches) in PSR-12 instead of
31+
establishing new conventions.
32+
33+
# 3. Scope
34+
35+
## 3.1. Goals
36+
37+
This PSR shares the same goals as PSR-2.
38+
39+
> The intent of this guide is to reduce cognitive friction when scanning code from
40+
> different authors. It does so by enumerating a shared set of rules and expectations
41+
> about how to format PHP code.
42+
> When various authors collaborate across multiple projects, it helps to have one set
43+
> of guidelines to be used among all those projects. Thus, the benefit of this guide is
44+
> not in the rules themselves, but in the sharing of those rules.
45+
46+
This PSR is an extension of PSR-2, and therefore also an extension of PSR-1. The basis of
47+
PSR-12 is PSR-2 and therefore a list of differences is provided below to assist with migration
48+
but it should be considered as an independent specification.
49+
50+
This PSR will include coding style guidelines related to new functionality added to PHP
51+
after the publication of PSR-2; this includes PHP 5.5, PHP 5.6 and PHP 7.0. This PSR will
52+
also include clarifications on the text of PSR-2, as described in the PSR-2 Errata.
53+
54+
## 3.2. Non-Goals
55+
56+
It is not the intention of this PSR to add entirely new coding style guidelines. PSR-12 will
57+
also not change anything stipulated in PSR-1 and PSR-2.
58+
59+
# 4. Approaches
60+
61+
The overarching approach is to attempt to apply existing PSR-2 styling and rationale to
62+
new functionality as opposed to establishing new conventions.
63+
64+
## 4.1. Strict Types Declarations
65+
66+
There was a discussion about whether or not strict types should be enforced in the standard
67+
https://github.com/cs-extended/fig-standards/issues/7. All were in agreement we should only
68+
use a MUST or MUST NOT statement and avoid the use of a SHOULD statement and nobody wanted
69+
to say that strict types could not be declared. The discussion was whether it should be
70+
considered a coding style item which should be covered or whether it was out of scope and it
71+
was decided to be out of scope of a coding style guide.
72+
73+
## 4.2. Finally and Return Types Declaration Spacing
74+
75+
Numerous different options were suggested and they can be seen
76+
[here for return type declarations](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-returntypesspacing-php) or
77+
[here for finally blocks](https://gist.github.com/michaelcullum/c025f3870c9ea1dd2668#file-finallyblocks-php)
78+
and the current implementation was chosen due to consistency with other parts of the PSR-12
79+
specification that came from PSR-2.
80+
81+
## 4.3. Enforcing short form for all type keywords
82+
83+
PHP 7.0 introduced [scalar types declaration](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration)
84+
which does not support long type aliases. Therefore it makes sense to enforce primary short type forms to be used to
85+
have uniform syntax and prevent possible confusion.
86+
87+
## 4.4. Public Survey
88+
89+
In order to settle things using data, survey was conducted and responses from 142 people
90+
including 17 project representatives were gathered:
91+
92+
### 4.4.1. PHP-FIG Representative Results
93+
94+
| 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 |
95+
| -------------- | ------- | ---------------------------------------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------------------------------- |------------------------------- |------------------------------------ | ----------------------------------- | ---------------------- |--------------------------- | ----------------------------------- | --------------------------- | -------------------------- |
96+
| Alexander Makarov | Yii framework | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
97+
| Korvin Szanto | concrete5 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
98+
| Leo Feyer | Contao | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
99+
| Larry Garfield | Drupal | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ❌ | ✓ | ✓ |
100+
| André R. | eZ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
101+
| Jan Schneider | Horde | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
102+
| Karsten Dambekalns | Neos and Flow | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
103+
| Andres Gutierrez | Phalcon | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
104+
| Ryan Thompson | PyroCMS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ |
105+
| Matteo Beccati | Revive Adserver | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ |
106+
| Damian Mooyman | SilverStripe | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
107+
| Brian Retterer | Stormpath PHP SDK | ✓ | ✓ | ✓ | ❌ | ❌ | ✓ | ❌ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ❌ | ❌ |
108+
| Matthew Weier O'Phinney | Zend Framework | ❌ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
109+
| Jordi Boggiano | Composer | ❌ | ❌ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
110+
| Ben Marks | Magento | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
111+
| Chuck Burgess | PEAR | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
112+
| | **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|
113+
114+
### 4.4.2. General non-representative voters
115+
116+
| Question | For | Against | Percentage For |
117+
| -------- | --- | ------- | -------------- |
118+
| Compound namespaces required depth | 114 | 12 | 89.47% |
119+
| Header statement grouping and ordering | 113 | 13 | 88.5% |
120+
| Declare statements must each be on their own line | 120 | 6 | 95% |
121+
| Declare statements in PHP files containing markup | 119 | 7 | 94.12% |
122+
| Declare statements have no spaces | 116 | 10 | 91.38% |
123+
| Block declare statement formatting | 118 | 8 | 93.22% |
124+
| `new` keyword usage, parenthesis required | 116 | 10 | 91.38% |
125+
| Return type declaration formatting | 115 | 11 | 90.43% |
126+
| Use statement leading slashes disallowed | 118 | 8 | 93.22% |
127+
| Block namespace declaration formatting | 120 | 6 | 95% |
128+
| General operator spacing | 123 | 3 | 97.56% |
129+
| Try, Catch, Finally formatting | 124 | 2 | 98.39% |
130+
| Anonymous class declaration formatting | 117 | 9 | 92.31% |
131+
| Keyword casing, only lower case | 124 | 2 | 98.39% |
132+
| Type keywords, short form only | 121 | 5 | 95.87% |
133+
134+
## 4.5. Multiline Function Arguments Mixed With Multiline Return
135+
136+
A potential readability issue [was raised on the mailing list](https://groups.google.com/d/msg/php-fig/ULSL4gqK8GY/cgDELuPOCQAJ).
137+
We reviewed options for changes to the specification that could provide better readability and
138+
the floated option was to require a blank line after the opening bracket of a function if the
139+
arguments and the return are both multiline. Instead it was pointed out that this specification
140+
_already_ allows you to decide where you'd like to add blank lines and so we will leave it to
141+
the implementors to decide.
142+
143+
# 5. Changelog from PSR-2
144+
145+
Please note this changelog is not a verbose list of changes from PSR-2 but highlights the most
146+
notable changes. It should be considered a new specification and therefore you should read the
147+
specification for a full understanding of its contents.
148+
149+
## 5.1. New Statements
150+
151+
* Lowercase for all keywords - Section 2.5
152+
* Short form for all type keywords - Section 2.5
153+
* Use statement grouping - Section 3
154+
* Use statement blocks - Section 3
155+
* Declare statement/Strict types declaration usage - Section 3
156+
* Parentheses are always required for class instantiation - Section 4
157+
* Typed properties - Section 4.3
158+
* Return type declarations - Section 4.5
159+
* Variadic and reference argument operators - Section 4.5
160+
* Type hints - Section 4.5
161+
* Add finally block - Section 5.6
162+
* Operators - Section 6
163+
* Unary operators - Section 6.1
164+
* Binary operators - Section 6.2
165+
* Ternary operators - Section 6.3
166+
* Anonymous classes - Section 8
167+
168+
## 5.2. Clarifications and Errata
169+
170+
* Adjust 'methods' to 'methods and functions' in a number of instances - Throughout
171+
* Adjust references to classes and interfaces to also include traits - Throughout
172+
* StudlyCaps meaning clarified as PascalCase - Section 2.1
173+
* The last line should not be blank but contain an EOL character - Section 2.2
174+
* Blank lines may be added for readability except where explicitly forbidden within the PSR - Section 2.3
175+
* PSR-2 errata statement about multi-line arguments - Section 4
176+
* PSR-2 errata statement about extending multiple interfaces - Section 4
177+
* Forbid blank lines before/after closing/opening braces for classes - Section 4
178+
179+
# 6. People
180+
181+
## 6.1. Editor:
182+
* Korvin Szanto
183+
184+
## 6.2. Sponsor:
185+
186+
* Chris Tankersley
187+
188+
## 6.3. Working Group Members:
189+
190+
* Alessandro Lai
191+
* Alexander Makarov
192+
* Michael Cullum
193+
* Robert Deutz
194+
195+
## 6.4. Special Thanks
196+
197+
* Michael Cullum for drafting the original specification
198+
* Alexandar Makarov for coordinating the draft during PHP-FIG 2.0
199+
* Cees-Jan Kiewiet for moral support
200+
201+
# 7. Votes
202+
203+
* **Entrance Vote:** https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/php-fig/P9atZLOcUBM/_jwkvlYKEAAJ
204+
* **Approval Vote:** https://groups.google.com/forum/#!topic/php-fig/1uaeSMaDGbk
205+
206+
# 8. Relevant Links
207+
208+
_**Note:** Order descending chronologically._
209+
210+
* [Inspiration Mailing List Thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/php-fig/wh9avopSR9k)
211+
* [Initial Mailing List PSR Proposal Thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/php-fig/MkFacLdfGso)

0 commit comments

Comments
 (0)