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关键字都应该使用小写字母,如truefalsenull
  • 一行代码的长度不建议有硬限制;软限制必须为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-Za-z0-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编码规范(中文版)

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注

昵称 *