This document describes the process and discussions that led to the Extended Coding Style PSR. Its goal is to explain the reasons behind each decision.
PSR-2 was accepted in 2012 and since then a number of changes have been made to PHP, most notably recent changes for PHP 7, which have implications for coding style guidelines. Whilst PSR-2 is very comprehensive of PHP functionality that existed at the time of writing, new functionality is very open to interpretation. PSR-12 seeks to provide a set way that both coding style tools can implement, projects can declare adherence to and developers can easily relate on between different projects for these coding style reducing cognitive friction.
PSR-2 was created based upon the common practices of the PHP-FIG projects at the time but ultimately this meant it was a compromise of many of the different projects' guidelines. The repercussions of projects changing their coding guidelines to align with PSR-2 (Almost all projects do align with PSR-1, even if it is not explicitly stated) were seen to be too great (losing git history, huge changesets and breaking existing patches/pull requests).
PSR-2 required adopters to reformat large amounts of existing code which stifled adoption. To help alleviate this issue with PSR-12, we have taken a more prescriptive approach and defined the standards for new language features as they are released.
However it is for a lack of wanting to be dictatorial that we will aim to apply PSR-2 styling, rationale and stances (Described in Section 4, Approaches) in PSR-12 instead of establishing new conventions.
This PSR shares the same goals as PSR-2.
The intent of this guide is to reduce cognitive friction when scanning code from different authors. It does so by enumerating a shared set of rules and expectations about how to format PHP code. When various authors collaborate across multiple projects, it helps to have one set of guidelines to be used among all those projects. Thus, the benefit of this guide is not in the rules themselves, but in the sharing of those rules.
This PSR is an extension of PSR-2, and therefore also an extension of PSR-1. The basis of PSR-12 is PSR-2 and therefore a list of differences is provided below to assist with migration but it should be considered as an independent specification.
This PSR will include coding style guidelines related to new functionality added to PHP after the publication of PSR-2; this includes PHP 5.5, PHP 5.6 and PHP 7.0. This PSR will also include clarifications on the text of PSR-2, as described in the PSR-2 Errata.
It is not the intention of this PSR to add entirely new coding style guidelines. PSR-12 will also not change anything stipulated in PSR-1 and PSR-2.
The overarching approach is to attempt to apply existing PSR-2 styling and rationale to new functionality as opposed to establishing new conventions.
There was a discussion about whether or not 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.
Numerous different options were suggested and they can be seen here for return type declarations or here for finally blocks and the current implementation was chosen due to consistency with other parts of the PSR-12 specification that came from PSR-2.
PHP 7.0 introduced scalar types 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.
In order to settle things using data, survey was conducted and responses from 142 people including 17 project representatives were gathered:
| 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 |
| 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% |
A potential readability issue was raised on the mailing list. 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.
Please note this changelog is not a verbose list of changes from PSR-2 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.
Note: Order descending chronologically.