PHP PSR代码规范

转载

zlixing 2022-05-30 17:09:23 博主文章分类：PHP

文章标签 PSR php 代码规范类名命名空间 文章分类 PHP 后端开发

PHP PSR代码规范_代码规范 PSR是PHP通用性框架小组（PHP Framework Interop Group）制定的PHP代码编写格式规范，是PHP开发的事实标准。

PSR是PHP通用性框架小组（PHP Framework Interop Group）制定的PHP代码编写格式规范，是PHP开发的事实标准。

截止到目前（2015年2月），正式发布过的PHP规范共有5个：

~~PSR 0 自动加载标准~~（已废弃，被PSR 4取代）
PSR 1 基本代码规范
PSR 2 代码风格指南
PSR 3 日志接口
PSR 4 改进的自动加载

那么使用、遵循PSR标准有什么必要和好处呢？统一的编码风格，可以让我们轻松愉悦地阅读他人的代码，以及编写让他人的代码。

就PSR规范本身来说，个人觉得是非常优秀、简洁的实践结晶。遵循这些标准，除了能使我们的代码更加可读之外，还能让我们的程序更加健壮，更能提高开发者的个人素养。

下面罗列一下PSR 1 ~ PSR 4的主要内容（已废弃的PSR 0不再介绍）：

PSR 1 基本代码规范

必须把PHP代码放在<?php ?>或<?= ?>标签中。不得使用其他PHP标签句法。
文件编码只使用UTF-8字符集编码，无BOM 格式。
一个源文件可以用来做声明（类、性状、函数、常量等），或者用来做一些有副作用的操作（如输出信息或处理数据），但不建议同时做这两件事。
应该避免的例子，既包含声明又有副作用

// 副作用：修改了ini配置
ini_set('error_reporting', E_ALL);
        
// 副作用：载入了文件
include "file.php";
        
// 副作用：产生了输出
echo "\n";
        
// 声明
function foo()
{
    // 函数体
}

提倡的例子，仅包含声明：

// 声明
  function foo()
{
    // 函数体
}

// 条件式声明不算做是副作用
if (! function_exists('bar')) {
    function bar()
    {
        // 函数体
    }
}

一个源文件中只能有一个类，并且每个类至少要有一级命名空间名，即一个顶级的组织名(vendor name)。类名必须使用骆驼式（StulyCase）写法

namespace Vendor\Model;

class StudlyCaps
{
    // 代码
}

类常量必须只由大写字母和下划线(_)组成：

  namespace Vendor\Model;
  
  class Foo
  {
      const VERSION = '1.0';
      const DATE_APPROVED = '2012-06-01';
  }

类属性命名依据喜好选择形如$StulyCaps、$camelCase 或者$unser_score 的风格，并在一个合理的范围内保持一致。
方法名必须使用驼峰式（camelCase）风格来声明，也就是首字母是小写的，后续单词的首字母都是大写的。

PSR 2 代码风格指南

代码使用4个空格来进行缩进，不使用制表符。
PHP文件使用Unix LF（换行）作为行结束符，最后要有一个空行，而且不能使用关闭标签?>（避免意料之外的输出错误）。
PHP关键字都应该使用小写字母，如true、false、null。
一行代码的长度不建议有硬限制；软限制必须为120个字符，建议每行代码80个字符或者更少。
在命名空间（namespace）的声明下面必须有一行空行，并且在导入（use）的声明下面也必须有一行空行。
类（class）的左花括号必须放到其声明下面自成一行，右花括号则必须放到类主体下面自成一行。
方法（method）的左花括号必须放到其声明下面自成一行，右花括号则必须放到方法主体的下一行。
所有的属性（property）和方法（method）必须有可见性声明；抽象（abstract）和终结（final）声明必须在可见性声明之前，而静态（static）声明必须在可见性声明之后。
控制结构的左花括号必须跟其放在同一行，右花括号必须放在该控制结构代码主体的下一行。

if ($a === true) {
    echo 'yes';
} else {
    echo 'no';
}

控制结构的左括号之后不可有空格，右括号之前也不可有空格。

PSR 3 日志接口

基础

符合PSR-3推荐规范的PHP日志记录器组件，必须包含一个实现Psr\Log\LoggerInterface接口的PHP类。要实现九个方法：

namespace Psr\Log;

interface LoggerInterface
{
    public function emergency($message, array $content = array());
    public function alert($message, array $content = array());
    public function critical($message, array $content = array());
    public function warning($message, array $content = array());
    public function notice($message, array $content = array());
    public function info($message, array $content = array());
    public function debug($message, $array $content = array());
    public function log($level, $message, array $content = array());
}

LoggerInterface 接口对外定义了八个方法，分别用来记录 RFC 5424 中定义的八个等级的日志：debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。
第九个是log方法，其第一个参数为记录的等级。可使用一个预先定义的等级常量作为参数来调用此方法，必须与直接调用以上八个方法具有相同的效果。如果传入的等级常量参数没有预先定义，则必须抛出Psr\Log\InvalidArgumentException 类型的异常。在不确定的情况下，使用者不该使用未支持的等级常量来调用此方法。

消息

每个方法都接受一个字符串，或者一个有__toString方法的对象作为message参数。实现者可以对传入的对象有特殊的处理。如果没有，实现者必须将它转换成字符串。
$message参数中可能包含一些可以被$context参数的数值所替换的占位符。占位符名字必须和$context数组类型参数的键名对应。占位符名字必须使用一对花括号来作为分隔符。在占位符和分隔符之间不能有任何空格。占位符名字应该只能由A-Z、a-z、0-9、_和.组成。其它的字符作为以后占位符规范的保留字。实现者可以使用占位符来实现不同的转义和翻译日志成文。因为用户并不知道上下文数据会是什么，所以不推荐提前转义占位符。

上下文

每个方法接受一个数组作为$context参数，用来存储不适合在字符串中填充的信息。数组可以包括任何东西。实现者必须确保他们尽可能包容的对$context参数进行处理。一个$context参数的给定值不可导致抛出异常，也不可产生任何PHP错误，警告或者提醒。
如果在$context参数中传入了一个异常对象，它必须以exception作为键名。记录异常轨迹是通用的模式，并且可以在日志系统支持的情况下从异常中提取出整个调用栈。实现者在将exception当做异常对象来使用之前必须去验证它是不是一个异常对象，因为它可能包含着任何东西。

助手类和接口

Psr\Log\AbstractLogger类可以让你通过继承它，并通用的log方法来方便的实现LoggerInterface接口。而其他八个方法将会把消息和上下文转发给log方法。
类似的，使用Psr\Log\LoggerTrait只需要你实现通用的log方法。注意，特性是不能用来实现接口的，所以你依然需要在你的类中implement LoggerInterface。
Psr\Log\NullLogger是和接口一起提供的。它在没有可用的日志记录器时，可以为使用日志接口的用户们提供一个后备的“黑洞”。但是，当$context参数的构建非常耗时的时候，直接判断是否需要记录日志可能是个更好的选择。
Psr\Log\LoggerAwareInterface只有一个setLogger(LoggerInterface $logger)方法，它可以在框架中用来随意设置一个日志记录器。
Psr\Log\LoggerAwareTrait特性可以被用来在各个类中轻松实现相同的接口。通过它可以访问到$this->logger。
Psr\Log\LogLevel类拥有八个日志等级的常量。

namespace Psr\Log;

class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}