PSR 12 编码风格指南补充 - 说明文档 「审阅中」
1. 摘要
本文档描述了创建编码风格补充 PSR 的过程和讨论。目标是解释每个决定背后的原因
2. 何必?
PSR-2 于 2012 年被接受，自那时起，PHP 语言做出做了一系列的更改，其中最引人注目的是 PHP 7 的最新变化，这深深影响了 PHP 编码风格指南
虽然 PSR-2 非常全面地介绍了编写规范时已经存在的 PHP 功能，但新功能非常易于解释。
PSR-12 寻求提供一种编码风格工具可以实现的设置方式，项目可以声明遵守这些编码风格从而减少认知摩擦，然后开发人员可以轻松地协调不同项目
PSR-2 是根据当时 PHP-FIG 项目的常见做法创建的，最终的规范对是许多不同项目指导方针的妥协。 改变项目的编码准则以遵循 PSR-2 规范 ( 几乎所有项目都与PSR-1保持一致，即使没有明确说明 ) 所 带来的影响太大了 ( 失去了 git 历史，巨大的变更集和破坏了现有的补丁/拉取请求 )
PSR-2 要求采用者重新格式化大量阻碍采用的现有代码。 为了帮助 PSR-12 解决这个问题，我们采用了更具说明性的方法，并且在发布新语言功能时就定义了标准。 我们希望它有更好的被采用的机会，因为这个规范是在编写大量代码之前定义的。
然而，由于缺乏独立性，我们的目标是在 PSR-12 中应用 PSR-2 样式、解释和立场 （ 第 4 节中介绍 ），而不是建立新的约定
3. 正文
3.1. 目标
此 PSR 和 PSR-2 有着共同的目标
本规范希望通过制定一系列规范化 PHP 代码的规则，以减少在浏览不同作者的代码时，因代码风格的不同而造成不便
此 PSR 是 PSR-2 的延伸，因此也是 PSR-1 的延伸。 PSR-12 的基础是 PSR-2，因此下面会提供了一系列差异来帮助进行移植，但它应该被视为一个独立的规范。
此 PSR 将包含 PSR-2 发布后添加到 PHP 中的新功能相关的编码风格指南，包括 PHP 5.5，PHP 5.6 和 PHP 7.0。 正如 PSR-2 勘误中所述，此 PSR 还将包含有关 PSR-2 文本的说明
3.2. 非目标
此 PSR 并不打算创建全新的编码风格指南。
PSR-12 也不会改变 PSR-1 和 PSR-2 中规定的任何内容
4. 方案
总体的方案是尝试将现有的 PSR-2 样式和基本原理应用到新功能中，而不是建立新的约定
4.1. 严格类型声明
曾经有一个关于是否在 标准中强制使用严格类型的讨论。 所有人都同意我们只应使用 MUST 或 MUST NOT 语句，并避免使用 SHOULD 语句，并且没有人想说不能声明严格类型。
讨论的是它是否应该被视为一种应该被覆盖的编码风格项目，或者它是否超出了范围。
最后的决定是它超出编码风格指南的范围
4.2. 最终 ( Finally ) 和返回类型声明中的空白符
提出了许多不同的选项，可以在这里查看 返回类型声明 or 最终 ( finally ) 块
作出这些选择的原因是为了和来自 PSR-2 的 PSR-12 中的其它部分保持一致
4.3. 为所有类型关键字强制使用简写形式
PHP 7.0 引入了 标量类型声明，但它并不支持长类型的别名。 因此，强制使用主要的短型格式可以统一语法和防止可能的混淆。
4.4. 公开调查
为了使用数据来解决问题，我们进行了一些调查，收集了包括 17 名项目代表在内的 142 人的回复
4.4.1. FIG 代表投票结果
| 代表 | 项目 | 复合命名空间的深度不能超过 1 | 头部声明分组和排序 | 声明语句必须各自独占一行 | PHP 文件中的声明语句可以包含标记 | 声明语句没有空白符 | 块声明语句格式 | new 关键用法，需要括号 |
返回类型声明格式 | use 声明中不许有前导的斜杠 | 命名空间声明块的格式 | 一般操作符空格 | Try, Catch, Finally 格式 | 匿名类声明格式 | 关键字大小写, 只允许小写 | 关键字类型，只允许简短格式 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Alexander Makarov | Yii 框架 | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 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 框架 | ❌ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Jordi Boggiano | Composer | ❌ | ❌ | ❌ | ✓ | ✓ | ✓ | ❌ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Ben Marks | Magento | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Chuck Burgess | PEAR | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 总计: | 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 |
4.4.2. 一般非代表投票者
| 问题 | 通过 | 反对 | 通过比例 |
|---|---|---|---|
| 复合命名空间需要深度 | 114 | 12 | 89.47% |
| 头部声明分组和排序 | 113 | 13 | 88.5% |
| 声明语句必须各自独占一行 | 120 | 6 | 95% |
| PHP 文件中的声明语句可以包含标记 | 119 | 7 | 94.12% |
| 声明语句没有空白符 | 116 | 10 | 91.38% |
| 块声明语句格式 | 118 | 8 | 93.22% |
new 关键用法，需要括号 |
116 | 10 | 91.38% |
| 返回类型声明格式 | 115 | 11 | 90.43% |
| use 声明中不许有前导的斜杠 | 118 | 8 | 93.22% |
| 命名空间声明块的格式 | 120 | 6 | 95% |
| 一般操作符空格 | 123 | 3 | 97.56% |
| Try, Catch, Finally 格式 | 124 | 2 | 98.39% |
| 匿名类声明格式 | 117 | 9 | 92.31% |
| 关键字大小写, 只允许小写 | 124 | 2 | 98.39% |
| 关键字类型，只允许简短格式 | 121 | 5 | 95.87% |
4.5. 多行函数参数混合多行返回
邮件列表中有人提出了潜在的 可读性问题。
我们复查了规范中所有可以带来更好可读性的变更选项，其中最亮眼的变更选项是： 如果参数和返回都是多行的话，则需要在函数的开头括号后面添加一个空行。
另一些人则提出了相反的意见：此规范已允许自由决定要添加空行的位置
因此我们会将其留给实现人员自由决定。
5. 对比 PSR-2 的变更
请注意，此变更日志不是 PSR-2 的详细变化列表，但突出了最显着的变化。 这些变更应该被认为是一个新的规范，因此你应该阅读规范以充分理解其内容。
5.1. 新增的声明
- 所有的关键字小写 - 章节 2.5
- 所有类型关键字的简写格式 - 章节 2.5
- Use 声明分组 - 章节 3
- Use 声明块 - 章节 3
- 声明语句/严格类型声明的用法 - 章节 3
- 类实例化始终需要括号 - 章节 4
- 返回类型声明 - 章节 4.5
- 类型提示 - 章节 4.5
- 添加最终块 ( finally block ) - 章节 5.6
- 操作符 - 章节 6
- 匿名类 - 章节 8
5.2. 澄清和勘误表
- 在多个实例中调整 「 方法 」 为 「 方法和函数 」 - 始终
- 调整对类和接口的引用以包含特征 ( trait ) - 始终
- StudlyCaps 被澄清为 PascalCase - 章节 2.1
- 最后一行 不能 为空，而是包含 EOL 字符 - 章节 2.2
- 除 PSR 中明确禁止的地方外，可以通过添加空白行来提高可读性 - 章节 2.3
- PSR-2 中关于多行参数的勘误表 - 章节 4
- PSR-2 中关于扩展多个接口的勘误表 - 章节 4
- 禁止在类的关闭/打开花括号之前/之后使用空白行 - 章节 4
6. 参与人员
6.1. 撰稿者:
- Korvin Szanto
6.2. 发起者:
- Chris Tankersley
6.3. 工作组成员:
- Alessandro Lai
- Alexander Makarov
- Michael Cullum
- Robert Deutz
6.4. 特别鸣谢
- Michael Cullum for drafting the original specification
- Alexandar Makarov for coordinating the draft during FIG 2.0
- Cees-Jan Kiewiet for moral support
7. 表决结果
- Entrance Vote: https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/php-fig/P9atZLOcUBM/_jwkvlYKEAAJ
8. 参考文档
注意：顺序是按照时间顺序排列