首页 > 代码库 > 我也学php：编码规范/翻译自PSR

我也学php：编码规范/翻译自PSR

2024-07-20 16:07:41   222人阅读

PHP社区百花齐放，拥有大量的函数库、框架和组件。PHP开发者通常会在自己的项目中使用若干个外部库，因而PHP代码遵循或尽量接近同一个代码风格就非常重要，可以让开发者方便地把多个代码库集成在自己的项目中。

框架互操作组(即PHP标准组)发布了一系列代码风格推荐标准，即PSR-0，PSR-1，PSR-2和PSR-3。 不要让这些名称所混淆，这些推荐仅是一些被其它项目所遵循的规则，如Drupal, Zend, Symfony, CakePHP, phpBB, AWS SDK, FuelPHP, Lithium等，你可以把这些规则用在自己的项目中，或者继续使用你自己的风格。

通常情况下，你的PHP代码应该遵循其中一项或多项标准，从而其他开发者可以方便地阅读和使用你的代码。这些标准都是在前一个标准 上附加新的规则，所以使用PSR-1就同时要求遵循PSR-0，但可以不遵循PSR-2。

可以使用PHP_CodeSniffer来检查代码是否符合这些标准，文本编辑器插件Sublime Text 2还能提供实时检查。如果不符合规范，可以使用Fabien Potencier提供的工具PHP Coding Standards Fixer自动修复，不用自己手工修复。

 PSR完整地址为:https://github.com/php-fig/fig-standards


PSR-0：类命名与autoloader之间的规范

PSR-0主要是对namespace和class命名规范进行约束，这个规范主要作用是使得autoloader函数能够根据完整的类名从硬盘中自动加载指定的类文件，其中涉及到的“强制”要求有以下几点：

  1. 完整的namespace和class命名必须符合结构:\<Vendor Name>\(<Namespace>\)*<Class Name>.php

  2. Vendor Name（开发者信息）必须是最顶层的namespace，这样可以防止自己类库与其他开发者类库出现命名冲突

  3. (<Namespace>\)*后面带有一个正则表达式中的星号，代表Namespace可以有0个或者多个

  4. 每个Namespace之间的分隔符在autoloader函数中，将会被转化为目录分隔符DIRECTORY_SEPARATOR

  5. Class Name即类名称中允许出现_（下划线），但是在autoloader函数中，该下划线也会转化为DIRECTORY_SEPARATOR

  6. 在autoloader函数中通过namespace和class命名来加载类文件时，类文件的后缀名必须是.php

  7. 对其中的英文字母大小写没有特殊要求

如果符合了上述要求，那么autoload代码就如下：

  1. <?php  

  2.   

  3. function autoload($className)  

  4. {  

  5.     $className = ltrim($className, ‘\\‘);  

  6.     $fileName  = ‘‘;  

  7.     $namespace = ‘‘;  

  8.     if ($lastNsPos = strrpos($className, ‘\\‘)) {  

  9.         $namespace = substr($className, 0, $lastNsPos);  

  10.         $className = substr($className, $lastNsPos + 1);  

  11.         $fileName  = str_replace(‘\\‘, DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;  

  12.     }  

  13.     $fileName .= str_replace(‘_‘, DIRECTORY_SEPARATOR, $className) . ‘.php‘;  

  14.   

  15.     require $fileName;  

  16. }  


  1. \Doctrine\Common\IsolatedClassLoader => /path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php  

  2. \Symfony\Core\Request => /path/to/project/lib/vendor/Symfony/Core/Request.php  

  3. \Zend\Acl => /path/to/project/lib/vendor/Zend/Acl.php  

  4. \Zend\Mail\Message => /path/to/project/lib/vendor/Zend/Mail/Message.php  

  5. \namespace\package\Class_Name => /path/to/project/lib/vendor/namespace/package/Class/Name.php  

  6. \namespace\package_name\Class_Name => /path/to/project/lib/vendor/namespace/package_name/Class/Name.php  


PSR-1：简单编码规范

原文中的 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 等关键字含义请参与RFC 2119文档。并且本文中不会对这些关键字进行翻译。

  1. 代码文件中MUST使用<?php ?>和<?= ?>两个代码标签；文件编码MUST使用UTF-8必须不包含BOM。

  2. 单个代码文件SHOULD要么用于声明类，函数或者常量等符号，要么用于进行一些会产生副作用（Side effects）的计算操作，比如输出和改变全局的设置。SHOULD NOT（不建议）同时在一个单文件中完成这两项工作。

  3. 命名空间和类名称MUST符合PSR_0规范

  4. 类名称声明MUST符合StudlyCaps（大写骆驼拼写法）

  5. 类中常量MUST使用全部大写，并使用_(下划线)作为分割符

  6. 函数名称声明MUST符合camelCase（小写骆驼拼写法）

PSR-2：编码风格

针对PHP文件

  1. 所有的PHP文件MUST使用Unix的LF作为行结尾

  2. 所有的PHP文件MUST是以单一的空白行结尾

  3. 在纯PHP文件中MUST省略文件结尾的?>标记

针对文件行

  1. MUST NOT对每一行的长度进行硬限制(Hard Limit)

  2. 每一个行长度软限制(Soft Limit)MUST为120个字符。如果样式检查的软件发现文件不符合该软限制时MUST给予warn但是MUST NOT给予error

  3. 每一行SHOULD NOT 超过80个字符。如果实在是超过80个字符，SHOULD分割为多行

  4. 每一个非空白行后面MUST NOT有多余的尾随空格

  5. 空白行 may（可以）被添加来提高代码的可读性，以及用于分割不相关代码

  6. 每一行MUST NOT超过一条语句

  7. 在命名空间声明行后，MUST有一个空白行

文本缩进

  1. 代码MUST 使用4个空格来进行缩进，MUST NOT使用tabs

PHP关键字大小写

  1. PHP关键字包括true, false,null在内，MUST 使用小写

命名空间和Use声明

  1. 在命名空间声明行后，MUST有一个空白行

  2. Use语句MUST在命名空间声明行后面

  3. 每一行MUST只能有一个Use声明

  4. 所有的Use语句后面，必须有一个空白行

  1. <?php  

  2. namespace Vendor\Package;  

  3.   

  4. use FooClass;  

  5. use BarClass as Bar;  

  6. use OtherVendor\OtherPackage\BazClass;  

  7.   

  8. // ... additional PHP code ...  

类声明：Extents和implements

  1. 类声明的{}大括号必须在两个独立行中

  2. 如果类声明中有extends和implements，那么它们MUST与类声明在同一行

  3. 如果同时有extends与implements，那么必须先写extends，再写implements

  4. 如果implements列表有多个，may把他们分割到多行中，每一行单独缩进。如果这样做，那么第一个implements就MUST在新行，并且每个implements单独占用一行。

  1. <?php  

  2. namespace Vendor\Package;  

  3.   

  4. use FooClass;  

  5. use BarClass as Bar;  

  6. use OtherVendor\OtherPackage\BazClass;  

  7.   

  8. class ClassName extends ParentClass implements  

  9.     \ArrayAccess,  

  10.     \Countable,  

  11.     \Serializable  

  12. {  

  13.     // constants, properties, methods  

  14. }  


类声明/函数声明：abstract，final，static

  1. 如果一个类或者函数在声明时，其中包含abstract，final，static三个关键字，那么与可见性关键字(public private protected)之间顺序为：abstarct 和final Must在可见性关键字之前；而static MUST在可见性关键字之后


类属性

  1. 每一个类属性MUST指定它们的可见性

  2. MUST NOT使用var关键字来声明一个类属性

  3. 每一条语句MUST声明单个属性

  4. SHOULD NOT使用_（下划线）作为属性名称的开头来表示属性为protected或private

方法声明与方法参数

  1. 每一个方法MUST显示指定它们的可见性

  2. SHOULD NOT使用_（下划线）作为方法名称的开头来表示方法为protected或private

  3. 方法名称后面MUST NOT带有空格。并且方法的大括号{}MUST分别在单独的行

  4. 方法的括号()内部的前后MUST NOT有空格，

  5. 方法的每一个参数后面MUST NOT 有空格，多个参数之间的逗号后面MUST 有空格。

  6. 含有默认值的参数MUST 放到参数类别后面

  7. 参数列表may被分割为多行，每行缩进一次；（括号紧跟在行数名后面，）在单独一行，并且与函数声明缩进对齐，后面紧跟一个空格和函数的大括号{。每一个参数MUST在单独行。

  1. <?php  

  2. namespace Vendor\Package;  

  3.   

  4. class ClassName  

  5. {  

  6.     public function foo($arg1, &$arg2, $arg3 = [])  

  7.     {  

  8.         // method body  

  9.     }  

  10.      public function aVeryLongMethodName(  

  11.         ClassTypeHint $arg1,  

  12.         &$arg2,  

  13.         array $arg3 = []  

  14.     ) {  

  15.         // method body  

  16.     }  

  17. }  

函数调用

  1. 在调用函数时，函数名称与(之间MUST NOT有空格，（和）与参数之间MUST NOT 有空格。

  2. 方法的每一个参数后面MUST NOT 有空格，多个参数之间的逗号后面MUST 有空格。

  3. 调用参数过长时，May把参数分为多行，每一行一个参数，并且拥有一个缩进。函数的(紧跟在函数名后，）最后一个参数后面的一行，并且不能有缩进。

  1. <?php  

  2. bar();  

  3. $foo->bar($arg1);  

  4. Foo::bar($arg2, $arg3);  

  5.   

  6. $foo->bar(  

  7.     $longArgument,  

  8.     $longerArgument,  

  9.     $muchLongerArgument  

  10. );  


控制结构

PHP中包含if/else/elseif，switch/case，while/dowhile，for，foreach，try/catch六种控制结构，它们的编码规范有一部分共性：

  1. 控制关键字后面MUST有一个空格

  2. 控制结构开括号（后面MUST NOT有空格

  3. 控制结构闭括号）前面MUST NOT有空格

  4. 控制结构开括号(与大括号}之间MUST有一个空格

  5. 控制结构体MUST缩进一次

  6. 控制结构闭大括号}必须在控制结构体后单独的一行

它们之间除了上述共性以外，还有各自的规范。

控制结构：if/elseif/else

具体的if编码规范见下述实例

  1. <?php  

  2. if ($expr1) {  

  3.     // if body  

  4. } elseif ($expr2) {  

  5.     // elseif body  

  6. } else {  

  7.     // else body;  

  8. }  

请注意上述的空格，括号开闭的位置。

控制结构：switch/case

具体的switch编码规范见下述实例，请注意它们的空格，括号开闭的位置。

  1. <?php  

  2. switch ($expr) {  

  3.     case 0:  

  4.         echo ‘First case, with a break‘;  

  5.         break;  

  6.     case 1:  

  7.         echo ‘Second case, which falls through‘;  

  8.         // no break  

  9.     case 2:  

  10.     case 3:  

  11.     case 4:  

  12.         echo ‘Third case, return instead of break‘;  

  13.         return;  

  14.     default:  

  15.         echo ‘Default case‘;  

  16.         break;  

  17. }  

  1. 每一个case MUST相对于switch有一个缩进。

  2. 如果一个case没有break或者return之类中断语句，那么必须在它相应位置注视// no break

控制结构：while/dowhile

具体的while编码规范见下述实例，请注意它们的空格，括号开闭的位置。

  1. <?php  

  2. while ($expr) {  

  3.     // structure body  

  4. }  

  5. do {  

  6.     // structure body;  

  7. } while ($expr);  


控制结构：for

具体的for编码规范见下述实例，请注意它们的空格，括号开闭的位置。

  1. <?php  

  2. for ($i = 0; $i < 10; $i++) {  

  3.     // for body  

  4. }  


控制结构：foreach

具体的foreach编码规范见下述实例，请注意它们的空格，括号开闭的位置。

  1. foreach ($iterable as $key => $value) {  

  2.     // foreach body  

  3. }  


控制结构：try/catch

具体的try编码规范见下述实例，请注意它们的空格，括号开闭的位置。

  1. <?php  

  2. try {  

  3.     // try body  

  4. } catch (FirstExceptionType $e) {  

  5.     // catch body  

  6. } catch (OtherExceptionType $e) {  

  7.     // catch body  

  8. }  

闭包

  1. function和use关键字与括号（之间MUST有一个空格

  2. 闭包的大开括号MUST与括号）在空一行，并且之间有一个空格

  3. 闭包的大闭括号MUST与闭包实体部分分割开，在单独一行；并且与闭包语句‘;’之间没有空格

  4. 闭包的function 和use的参数与括号（）之间MUST NOT有空格，并且多个参数之间的‘，’前面没有空格，后面有一个空格

  5. 如果闭包的参数有默认值，那么它MUST放在参数列表的后面

  6. 闭包的参数列表可以分多行，具体的请参考实例

  1. <?php  

  2. $closureWithArgs = function ($arg1, $arg2) {  

  3.     // body  

  4. };  

  5.   

  6. $closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {  

  7.     // body  

  8. };  

  9. $longArgs_noVars = function (  

  10.     $longArgument,  

  11.     $longerArgument,  

  12.     $muchLongerArgument  

  13. ) {  

  14.    // body  

  15. };  

  16.   

  17. $noArgs_longVars = function () use (  

  18.     $longVar1,  

  19.     $longerVar2,  

  20.     $muchLongerVar3  

  21. ) {  

  22.    // body  

  23. };  

  24.   

  25. $longArgs_longVars = function (  

  26.     $longArgument,  

  27.     $longerArgument,  

  28.     $muchLongerArgument  

  29. ) use (  

  30.     $longVar1,  

  31.     $longerVar2,  

  32.     $muchLongerVar3  

  33. ) {  

  34.    // body  

  35. };  

  36.   

  37. $longArgs_shortVars = function (  

  38.     $longArgument,  

  39.     $longerArgument,  

  40.     $muchLongerArgument  

  41. ) use ($var1) {  

  42.    // body  

  43. };  

  44.   

  45. $shortArgs_longVars = function ($arg) use (  

  46.     $longVar1,  

  47.     $longerVar2,  

  48.     $muchLongerVar3  

  49. ) {  

  50.    // body  

  51. };  

PSR-3：日志接口

PSR-3是关于系统日志的接口的开发规范，先不翻译，后面复习php日志处理再回来翻译

链接：https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md


我也学php：编码规范/翻译自PSR


联系
我们