PSR规范

蔚落 2022-05-18 01:08 289阅读 0赞

> PSR是由**FIG**这个组织制定的PHP规范，官网是 www.php-fig.org

## PSR-0：自动加载 ##

[PSR-0][] 是FIG出的第一套规范，主要是制定了一些自动加载标准。不过 PSR-0 已经被标记为 **Deprecated（已弃用）**，自动加载的新规范为 [PSR-4][]。

## PSR-1：基本代码规范 ##

[PSR-1][] 规范包括了一些为确保共享PHP代码之间高水平的技术互操作性所需的标准编码元素。

1.  PHP源文件**必须**只使用`<?php`和`<?=`这两种标签。
2.  源文件中php代码的编码格式**必须**是不带字节顺序标记（BOM）的`UTF-8`。
3.  一个源文件**建议**只用来做声明（类、函数、常量等）或者只用来做一些引起副作用的操作（例如：输出信息、修改.ini配置等），但**不建议**同时做这两件事。
4.  命名空间（namespace）和类（class）**必须**遵守PSR-0/PSR-4自动加载标准。
5.  类名**必须**使用骆驼式（StudlyCaps）写法 (注：驼峰式的一种变种)。
6.  类中的常量**必须**只由大写字母和下划线组成。
7.  方法名**必须**使用驼峰式（camelCase）写法。

## PSR-2：代码样式 ##

[PSR-2][] 是对 PSR-1 规范的补充和扩展，主要是用于约束代码风格，多人协作开发时统一代码风格是很重要的。

1.  代码**必须**遵循 PSR-1 的基本代码规范。
2.  **必须**使用4个空格来缩进，不能使用Tab键。
3.  一行代码的长度不得有硬性限制，软限制必须是120字符，**建议**是最多80个字符。
4.  在`namespace`声明之后**必须**有一个空行，并且在`use`声明块之后**必须**有一个空行。
5.  声明类、方法的花括号**必须**单独写在一行。
6.  **必须**在所有属性和方法上声明可见性（public/protected/private），`abstract`和`final`必须在可见性之前声明，`static`必须在可见性之后声明。
7.  控制结构关键字，就是 if else while switch foreach等，后面**必须**要有一个空格。
8.  控制结构的左花括号**必须**与控制关键字在同一行，右花括号**必须**单独写在一行。

## PSR-3：日志接口 ##

[PSR-3][] 规范描述的是日志库的通用接口，主要目标是允许库以简单和通用的方式接收`Psr\Log\LoggerInterface`对象并将日志写入其中。

### Basics ###

1.  接口`LoggerInterface`暴露了8个方法，用于写8种级别的日志，包括`debug`,`info`,`notice`,`warning`,`error`,`critical`,`alert`,`emergency`。
2.  第九个方法`log($level, $message, $context)`，根据`$level`参数调用特定日志级别的方法，如果传入的日志 level 不存在，**必须**抛出一个`Psr\Log\InvalidArgumentException`异常。

### Message ###

1.  每个方法都接受一个字符串作为消息，或一个带有`__toString()`方法的对象。实现者可以对该入参进行特殊处理，最后**必须**都转换为字符串。
2.  `$message`中可以包含占位符，实现时可以用`$context`数组中的值替换。  
    
    
     *  占位符名称必须是`$context`数组中的键;
     *  占位符必须用花括号`{}`括起来，占位符名称与花括号之间不能再有空格；
     *  占位符名字应该只由大小写字母、数字、下划线、点组成。

### Context ###

1.  每个方法都接受一个`$context`数组作为上下文数据，该数组可以包含任何内容。

<?php
    
    namespace Psr\Log;
    
    /**
     * Describes a logger instance
     *
     * The message MUST be a string or object implementing __toString().
     *
     * The message MAY contain placeholders in the form: {foo} where foo
     * will be replaced by the context data in key "foo".
     *
     * The context array can contain arbitrary data, the only assumption that
     * can be made by implementors is that if an Exception instance is given
     * to produce a stack trace, it MUST be in a key named "exception".
     *
     */
    interface LoggerInterface
    {
        
    
        public function emergency($message, array $context = array());
        public function alert($message, array $context = array());
        public function critical($message, array $context = array());
        public function error($message, array $context = array());
        public function warning($message, array $context = array());
        public function notice($message, array $context = array());
        public function info($message, array $context = array());
        public function debug($message, array $context = array());
    
        public function log($level, $message, array $context = array());
    }

更多请查看[PSR-3规范][PSR-3]。

## PSR-4：自动加载 ##

[PSR-4][] 规范了如何从文件路径自动加载类，同时规范了自动加载文件的位置。

1.  术语`class`指的是类，接口，trait，和其他类似结构。
2.  一个完全限定类名具有以下形式：`\<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>`  
    
    
     *  必须具有顶级命名空间，也称为vendor namespace；
     *  可能具有一个或多个子命名空间；
     *  下划线（\_）没有任何特殊含义；
     *  必须区分大小写。
3.  加载一个完全限定类名对应的文件时：  
    
    
     *  在完全限定类名中, 不包含前面的命名空间分隔符，由一个顶级命名空间与一个或多个二级命名空间名称组成的命名空间前缀，对应于至少一个“base目录”；
     *  在命名空间前缀后面的二级命名空间名称对应于“base目录”中的一个子目录, 这里命名空间分隔符表示目录分隔符。子目录名称必须匹配到二级命名空间名称；
     *  最后的类名对应于以`.php`为后缀的文件名，且大小写也要相同。
4.  自动加载的实现一定不能抛出异常，一定不能引发任何级别的错误, 并且不应该有返回值。

### 举例 ###

<table> 
 <thead> 
  <tr> 
   <th>完全限定类名</th> 
   <th>命名空间前缀</th> 
   <th>Base目录</th> 
   <th>最终文件路径</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>\Acme\Log\Writer\File_Writer</td> 
   <td>Acme\Log\Writer</td> 
   <td>./acme-log-writer/lib/</td> 
   <td>./acme-log-writer/lib/File_Writer.php</td> 
  </tr> 
  <tr> 
   <td>\Aura\Web\Response\Status</td> 
   <td>Aura\Web</td> 
   <td>/path/to/aura-web/src/</td> 
   <td>/path/to/aura-web/src/Response/Status.php</td> 
  </tr> 
  <tr> 
   <td>\Symfony\Core\Request</td> 
   <td>Symfony\Core</td> 
   <td>./vendor/Symfony/Core/</td> 
   <td>./vendor/Symfony/Core/Request.php</td> 
  </tr> 
  <tr> 
   <td>\Zend\Acl</td> 
   <td>Zend</td> 
   <td>/usr/includes/Zend/</td> 
   <td>/usr/includes/Zend/Acl.php</td> 
  </tr> 
 </tbody> 
</table>

[PSR-0]: https://www.php-fig.org/psr/psr-0/
[PSR-4]: https://www.php-fig.org/psr/psr-4/
[PSR-1]: https://www.php-fig.org/psr/psr-1/
[PSR-2]: https://www.php-fig.org/psr/psr-2/
[PSR-3]: https://www.php-fig.org/psr/psr-3/