PHP PSR代码格式规范

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 格式。
  • 一个源文件可以用来做声明（类、性状、函数、常量等），或者用来做一些有副作用的操作（如输出信息或处理数据），但不建议同时做这两件事。
    应该避免的例子，既包含声明又有副作用： 
    <?php
// 副作用：修改了ini配置
ini_set('error_reporting', E_ALL);
		
// 副作用：载入了文件
include "file.php";
		
// 副作用：产生了输出
echo "<html>\n";
		
// 声明
function foo()
{
    // 函数体
}

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

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

// 条件式声明不算做是副作用
if (! function_exists('bar')) {
    function bar()
    {
        // 函数体
    }
}
  • 一个源文件中只能有一个类，并且每个类至少要有一级命名空间名，即一个顶级的组织名(vendor name)。类名必须使用骆驼式（StulyCase）写法 
    <?php
namespace Vendor\Model;

class StudlyCaps
{
    // 代码
}
  • 类常量必须只由大写字母和下划线(_)组成： 
      <?php
  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类。要实现九个方法：

<?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类拥有八个日志等级的常量。 
    <?php
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';
}

PSR 4 改进的自动加载

  • 术语「类」是一个泛称，它包含类、接口、trait 以及其他类似的结构；
  • 完全限定类名应该类似如下范例：\<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>
    • 完全限定类名必须有一个顶级命名空间（Vendor Name）；
    • 完全限定类名可以有多个子命名空间；
    • 完全限定类名应该有一个终止类名；
    • 下划线在完全限定类名中是没有特殊含义的；
    • 字母在完全限定类名中可以是任何大小写的组合；
    • 所有类名必须以大小写敏感的方式引用；
  • 当从完全限定类名载入文件时：
    • 在完全限定类名中，连续的一个或几个子命名空间构成的命名空间前缀（不包括顶级命名空间的分隔符），至少对应着至少一个基础目录。
    • 在「命名空间前缀」后的连续子命名空间名称对应一个「基础目录」下的子目录，其中的命名 空间分隔符表示目录分隔符。子目录名称必须和子命名空间名大小写匹配；
    • 终止类名对应一个以 .php 结尾的文件。文件名必须和终止类名大小写匹配；
  • 自动载入器的实现不可抛出任何异常，不可引发任何等级的错误；也不应返回值；

 

参考资料：

  1. PHP Standards Recommendations
  2. PHP标准化规范PSR 0、PSR 1、PSR 2、PSR 3、PSR 4
  3. PHP编码规范（中文版）
vim移动光标命令 git中merge和rebase的区别
相关笔记