PSR-12：扩展编码风格

扩展编码风格指南元文档

1.总结

本文档描述了导致扩展编码样式PSR的过程和讨论。其目标是解释每个决定背后的原因。

为什么要打扰？

PSR-2在2012年被接受，从那时起，PHP已经发生了许多变化，最显着的是PHP 7的最新变化，这些变化对编码风格指南有影响。虽然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还将包括对PSR-2文本的澄清，如PSR-2勘误表中所述。

3.2。非目标

PSR的目的并不是要添加全新的编码风格指南，PSR-12也不会改变PSR-1和PSR-2中规定的任何内容。

4.方法

总体方法是尝试将现有的PSR-2样式和基本原理应用于新功能，而不是建立新的约定。

4.1。严格的类型声明

讨论了是否应在标准https://github.com/cs-extended/fig-standards/issues/7中强制执行严格类型。所有人都同意我们应该只使用MUST或MUST NOT语句并避免使用SHOULD语句，没有人想说无法声明严格类型。讨论的是它是否应该被视为应该涵盖的编码风格项目，或者它是否超出范围并且决定超出编码风格指南的范围。

4.2。最后和返回类型声明间距

建议了许多不同的选项，它们可以在这里看到 返回类型声明或 这里的最终块， 并且由于与PSR-2的PSR-12规范的其他部分的一致性而选择了当前的实现。

4.3。强制执行所有类型关键字的简短形式

PHP 7.0引入了标量类型声明 ，它不支持长类型别名。因此，有必要强制使用主要的短类型表单来使用统一的语法并防止可能的混淆。

4.4。公众调查

为了使用数据解决问题，进行了调查，收集了包括17个项目代表在内的142人的回复：

4.4.1。PHP-FIG代表性结果

代表 项目 绝不能使用深度为2或更大的复合名称空间 标题语句分组和排序 声明语句必须各自独立 在包含标记的PHP文件中声明语句 声明语句没有空格： declare(strict_types=1); 阻止声明语句格式 new 关键字用法，需要括号 返回类型声明格式 使用语句前导斜杠不允许 阻止命名空间声明格式 一般操作员间距 尝试，捕获，最后格式化 匿名类声明格式 关键字套管，仅限小写 键入关键字，仅限简短形式
亚历山大马卡罗夫 Yii框架 ✓ ✓ ✓ ❌ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Korvin Szanto concrete5 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Leo Feyer Contao ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
拉里加菲尔德 Drupal的 ✓ ✓ ✓ ✓ ✓ ❌ ✓ ✓ ✓ ❌ ✓ ✓ ❌ ✓ ✓
安德烈·R 的eZ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Jan Schneider 部落 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Karsten Dambekalns Neos和Flow ✓ ✓ ✓ ✓ ❌ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
安德烈斯古铁雷斯 尔康 ❌ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
莱恩汤普森 PyroCMS ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ❌ ❌ ✓ ✓ ✓ ✓ ✓
Matteo Beccati Revive Adserver ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ❌ ✓ ✓ ✓ ✓
达米安·莫伊曼 SilverStripe ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Brian Retterer Stormpath PHP SDK ✓ ✓ ✓ ❌ ❌ ✓ ❌ ✓ ❌ ✓ ✓ ✓ ✓ ❌ ❌
Matthew Weier O'Phinney Zend框架 ❌ ✓ ✓ ❌ ✓ ✓ ✓ ❌ ✓ ✓ ✓ ✓ ✓ ✓ ✓
乔迪·博贾诺 作曲家 ❌ ❌ ❌ ✓ ✓ ✓ ❌ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
本马克斯 Magento的 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
查克伯吉斯 梨 ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
  总计： 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％
使用语句前导斜杠不允许 118 8 93.22％
阻止命名空间声明格式 120 6 95％
一般操作员间距 123 3 97.56％
尝试，捕获，最后格式化 124 2 98.39％
匿名类声明格式 117 9 92.31％
关键字套管，仅限小写 124 2 98.39％
键入关键字，仅限简短形式 121 五 95.87％

4.5。多线函数参数与多行返回混合

邮件列表中提出了潜在的可读性问题。我们检查了可以提供更好可读性的规范更改选项，浮动选项是在函数的开括号之后需要一个空行，如果参数和返回都是多行的。相反，有人指出，此规范 已经允许您决定添加空行的位置，因此我们将把它留给实现者来决定。

5.来自PSR-2的更改日志

请注意，此更改日志不是PSR-2更改的详细列表，但突出显示了最显着的更改。它应被视为新规范，因此您应阅读规范以全面了解其内容。

5.1。新陈述

  • 所有关键字的小写 - 第2.5节
  • 所有类型关键字的简写形式 - 第2.5节
  • 使用语句分组 - 第3节
  • 使用语句块 - 第3节
  • 声明语句/严格类型声明用法 - 第3节
  • 类实例化总是需要括号 - 第4节
  • 类型属性 - 第4.3节
  • 返回类型声明 - 第4.5节
  • Variadic和引用参数运算符 - 第4.5节
  • 类型提示 - 第4.5节
  • 添加finally块 - 第5.6节
  • 运营商 - 第6节
  • 一元算子 - 第6.1节
  • 二元算子 - 第6.2节
  • 三元运算符 - 第6.3节
  • 匿名课程 - 第8节

5.2。澄清和勘误

  • 在许多情况下将“方法”调整为“方法和函数” - 自始至终
  • 调整对类和接口的引用以包括特征 - 自整经
  • StudlyCaps意义澄清为PascalCase - 第2.1节
  • 最后一行不应为空，但包含EOL字符 - 第2.2节
  • 除了在PSR中明确禁止的情况外，可以添加空行以便于阅读 - 第2.3节
  • 关于多行论证的PSR-2勘误表 - 第4节
  • 关于扩展多个接口的PSR-2勘误声明 - 第4节
  • 在关闭/打开类的大括号之前/之后禁止空白行 - 第4节

6.人

6.1。编辑：

  • Korvin Szanto

6.2。赞助：

  • 克里斯坦克斯利

6.3。工作组成员：

  • 亚历山德罗·莱
  • 亚历山大马卡罗夫
  • 迈克尔库鲁姆
  • 罗伯特·道茨

6.4。特别谢谢

  • Michael Cullum起草原始规范
  • Alexandar Makarov在PHP-FIG 2.0期间协调草案
  • Cees-Jan Kiewiet获得道义支持

7.投票

  • 入场投票： https ： //groups.google.com/forum/？utm_medium = email＆utm_source = footer＃！msg / php- fig / P9atZLOcUBM / _jwkvlYKEAAJ
  • 审批投票： https ：//groups.google.com/forum/#！ topic / php-fig / iaeSMaDGbk

8.相关链接

注意：顺序按时间顺序递减。