PHP编码规范

整理自 PHP 标准规范

作为程序员来说,采用统一的编码风格是非常重要的。这将给未来代码的编写、阅读节省大量时间。这里整理一份自己的 PHP 编码规范。

动词说明:
  • 必须:严格遵守;
  • 禁止:一定不能这样做;
  • 应该:强烈建议这样做,但不强求;
  • 不该:强烈建议不这样做,但不强求;
  • 可以:选择性高一点。
一、基本代码规范
  1. 概览
  • PHP 代码 必须<?php 标签开始;
  • PHP 代码文件 必须 以不带 BOM 的 UTF-8 编码;
  • PHP 代码中 应该 只定义类、函数、常量等声明,或其他会产生「副作用」的操作(如:生成文件输出以及修改 .ini 配置文件等),二者只能选其一;
  • 命名空间以及类 必须 符合 PSR 的自动加载规范:PSR-4 中的一个;
  • 类的命名 必须 遵循 StudlyCaps 大写 开头的驼峰命名规范;
  • 类中的常量所有字母都 必须 大写,单词间用下划线分隔;
  • 方法名称 必须 符合 camelCase 式的小写开头驼峰命名规范。
  1. 文件
    2.1 PHP 标签及 PHP 代码 必须 使用 <?php ?> 长标签; 禁止 使用 <?= ?> 短输出标签,或其它自定义标签。
    2.2 字符编码 PHP 代码 必须 且只可使用不带 BOM 的 UTF-8 编码。
    2.3 副作用,一份 PHP 文件中 应该 要不就只定义新的声明,如类、函数或常量等不产生「副作用」的操作,要不就只书写会产生「副作用」的逻辑操作,但 不该 同时具有两者。

「副作用」(side effects) 一词的意思是,仅仅通过包含文件,不直接声明类、函数和常量等,而执行的逻辑操作。 「副作用」包含却不仅限于: 生成输出 直接的 require 或 include 连接外部服务 修改 ini 配置 抛出错误或异常 修改全局或静态变量 读或写文件等。

以下是一个反例,一份包含「函数声明」以及产生「副作用」的代码:

<?php 
// 「副作用」:修改 ini 配置 
ini_set('error_reporting', E_ALL);  

// 「副作用」:引入文件 
include "file.php";  

// 「副作用」:生成输出 
echo "\n";  

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

下面是一个正确的范例,一份只包含声明不产生「副作用」的代码:

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

// 条件声明 属于「副作用」

if (!function_exists('bar')) {
      function bar() {
          // 函数主体部分 
      }
} 
  1. 命名空间和类
    3.1命名空间以及类的命名 必须 遵循 PSR-4 规范。 根据规范,每个类都独立为一个文件,且命名空间至少有一个层次:顶级的组织名称(vendor name)。
    3.2 类的命名 必须 遵循 StudlyCaps 大写开头的驼峰命名规范。 PHP 5.3 及以后版本的代码 必须 使用正式的命名空间。
    例如:
<?php 
// PHP 5.3及以后版本的写法 
namespace Vendor\Model;

class Foo { } 
  1. 类的常量、属性和方法(此处的「类」指代所有的类、接口以及可复用代码块(traits))。
    4.1 常量,类的常量中所有字母都 必须 大写,词间以下划线分隔。
    4.2 属性,类属性 应该 统一小写开头的驼峰式 ($camelCase),修饰符 public、protected、private 必须 加上。
    4.3 方法,方法名称 必须 符合 camelCase() 式的小写开头驼峰命名规范,修饰符 public、protected、private 必须 加上。
    示例:
<?php
namespace Vendor\Model;

class Foo
{
      const VERSION = '1.0';
      const DATE_APPROVED = '2012-06-01';

      public $camelCase1;
      protected $camelCase2;
      private $camelCase3;

      public function camelCase()
      { 
           // do something ...
      }
}
二、编码风格规范
  1. 概览
  • 代码 必须 遵循基本代码规范;
  • 代码 必须 使用4个空格符而不是「Tab 键」进行缩进;
  • 每行的字符数 应该 软性保持在 80 个之内,理论上 禁止 多于 120 个,但同时 **禁止 **有硬性限制;
  • 每个 namespace 命名空间声明语句和 use 声明语句块后面,必须 插入一个空白行;
  • 类的开始花括号 { 必须 写在函数声明后自成一行,结束花括号 }必须 写在函数主体后自成一行;
  • 方法的开始花括号 { 必须 写在函数声明后自成一行,结束花括号 }必须 写在函数主体后自成一行;
  • 类的属性和方法 必须 添加访问修饰符(private、protected 以及 public),abstract 以及 final 必须 声明在访问修饰符之前,而 static 必须 声明在访问修饰符之后;
  • 控制结构的关键字后 必须 要有一个空格符,而调用方法或函数时则 禁止 加空格符;
  • 控制结构的开始花括号 { 必须 写在声明的同一行,而结束花括号 } 必须 写在主体后自成一行;
  • 控制结构的开始左括号后和结束右括号前,都 禁止 有空格符。

1.1 示例,以下例子程序简单地展示了以上大部分规范:

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{

      public function sampleFunction($a, $b = null)
      {
          if ($a === $b) {
               bar();
          } elseif ($a > $b) {
               $foo->bar($arg1);
          } else {
              BazClass::bar($arg2, $arg3);
          }
      }

      final public static function bar()
      {
          // 方法的内容
      }

}
  1. 通则
    2.1 基本编码准则
    代码 必须 符合 基本代码规范

2.2 文件
所有 PHP 文件 必须 以一个空白行作为结束。 纯 PHP 代码文件 必须 省略最后的 ?> 结束标签。

2.3 行
行的长度 禁止 有硬性的约束,软性的长度约束 应该 要限制在 120 个字符以内。
非空行后 禁止 有多余的空格符。
每行 禁止 存在多于一条语句。

2.4 缩进
代码 必须 使用 4 个空格符的缩进,禁止 用 tab 键。

备注:使用空格而不是「tab键缩进」的好处在于, 避免在比较代码差异、打补丁、重阅代码以及注释时产生混淆。 并且,使用空格缩进,让对齐变得更方便。

2.5 关键字以及 True/False/Null
PHP 所有关键字 必须 全部小写。
常量 true 、false 和 null 也 **必须 ** 全部小写。

  1. namespace 以及 use 声明
    namespace 声明后 必须 插入一个空白行。
    所有 use 必须 在 namespace 后声明。
    每条 use 声明语句 必须 只有一个 use 关键词。
    use 声明语句块后 必须 要有一个空白行。
    示例:
<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... 更多的 PHP 代码在这里 ...
  1. 类、属性和方法
    此处的「类」泛指所有的「class类」、「接口」以及「traits 可复用代码块」。

4.1 扩展与继承
关键词 extends 和 implements 必须 写在类名称的同一行。
类的开始花括号 必须 独占一行,结束花括号也 必须 在类主体后独占一行。

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // 这里面是常量、属性、类方法
}

implements 的继承列表也 可以 分成多行,这样的话,每个继承接口名称都 必须 分开独立成行,包括第一个。

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
\ArrayAccess,
\Countable,
\Serializable 
{
    // 这里面是常量、属性、类方法 
}

4.2 属性
每个属性都 必须 添加访问修饰符。
禁止 使用关键字 var 声明一个属性。
禁止 一条语句定义超过一个属性。
不该 使用下划线作为前缀,来区分属性是 protected 或 private。
示例:

<?php
namespace Vendor\Package;

class ClassName
{
      public $foo = null;
}

4.3 方法
所有方法都 必须 添加访问修饰符。
不该 使用下划线作为前缀,来区分方法是 protected 或 private。
方法名称后 禁止 有空格符,其开始花括号 必须 独占一行,结束花括号也 必须 在方法主体后单独成一行。
参数左括号后和右括号前 禁止 有空格。
示例:

<?php
namespace Vendor\Package;

class ClassName
{ 
      public function fooBarBaz($arg1, &$arg2, $arg3 = [])
      {
          // method body
      }
}

4.4 方法的参数
参数列表中,每个逗号后面 必须 要有一个空格,而逗号前面 禁止 有空格。
有默认值的参数,必须 放到参数列表的末尾。
参数类型为数组或对象的 应该 加上访问修饰符 array 或对应对象的类修饰。

<?php
namespace Vendor\Package;

class ClassName
{
      public function foo($arg1, &$arg2, array $arg3 = [])
      {
          // method body
      }
}

参数列表 可以 分列成多行,这样,包括第一个参数在内的每个参数都 必须 单独成行。 拆分成多行的参数列表后,结束括号以及方法开始花括号 必须 写在同一行,中间用一个空格分隔。

<?php
namespace Vendor\Package;

class ClassName
{
      public function aVeryLongMethodName(
          ClassTypeHint $arg1,
          &$arg2,
          array $arg3 = [] 
      ) {
          // 方法的内容
      }
 }

4.5 abstract、final 以及 static
需要添加 abstract 或 final 声明时,必须 写在访问修饰符前,而 static 则 必须 写在其后。

<?php
namespace Vendor\Package;

abstract class ClassName
{
      protected static $foo;
     
      abstract protected function zim();
    
      final public static function bar()
      {
          // method body
      }

}

4.6 方法及函数调用
方法及函数调用时,方法名或函数名与参数左括号之间 禁止 有空格,参数右括号前也 禁止 有空格。
每个参数前 禁止 有空格,但其后 必须 有一个空格。

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

参数 可以 分列成多行,此时包括第一个参数在内的每个参数都 必须 单独成行。

<?php
$foo->bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
  1. 控制结构
    控制结构的基本规范如下:
    控制结构关键词后 必须 有一个空格;
    左括号 (禁止 有空格;
    右括号 ) 前也 禁止 有空格;
    右括号 ) 与开始花括号 {必须 有一个空格;
    结构体主体 必须 要有一次缩进;
    结束花括号 } 必须 在结构体主体后单独成行。
    每个结构体的主体都 必须 被包含在成对的花括号之中,这能让结构体更加结构话,以及减少加入新行时,出错的可能性。

5.1 if、elseif 和 else
标准的 if 结构如下代码所示,请留意「括号」、「空格」以及「花括号」的位置, 注意 else 和 elseif 都与前面的结束花括号在同一行。

<?php
if ($expr1) {
      // if body
} elseif ($expr2) {
      // elseif body
} else {
      // else body;
}

5.2 switch 和 case
标准的 switch 结构如下代码所示,留意括号、空格以及花括号的位置。 case 语句 必须 相对 switch 进行一次缩进,而 break 语句以及 case 内的其它语句都 必须 相对 case 进行一次缩进。 如果存在非空的 case 直穿语句,主体里 必须 有类似 // no break 的注释。

<?php
switch ($expr) {
      case 0:
           echo 'First case, with a break';
           break;
      case 1:
           echo 'Second case, which falls through';
      // no break
      case 2:
      case 3:
      case 4:
           echo 'Third case, return instead of break';
           return;
      default:
           echo 'Default case';
           break;
}

5.3 while 和 do while
一个规范的 while 语句应该如下所示,注意其「括号」、「空格」以及「花括号」的位置。

<?php
while ($expr) {
      // structure body
}

标准的 do while 语句如下所示,同样的,注意其「括号」、「空格」以及「花括号」的位置。

<?php
do {
      // structure body;
} while ($expr);

5.4 for
标准的 for 语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。

<?php
for ($i = 0; $i < 10; $i++) {
      // for body
}

5.5 foreach
标准的 foreach 语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。

<?php
foreach ($iterable as $key => $value) {
      // foreach body
}

5.6 try,catch
标准的 try catch 语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。

<?php
try {
      // try body
} catch (FirstExceptionType $e) {
      // catch body
} catch (OtherExceptionType $e) {
      // catch body
}
  1. 闭包
    闭包声明时,关键词 function 后以及关键词 use 的前后都 必须 要有一个空格。
    开始花括号 必须 写在声明的同一行,结束花括号 必须 紧跟主体结束的下一行。
    参数列表和变量列表的左括号后以及右括号前,禁止 有空格。
    参数和变量列表中,逗号前 禁止 有空格,而逗号后 必须 要有空格。
    闭包中有默认值的参数 必须 放到列表的后面。
    标准的闭包声明语句如下所示,注意其「括号」、「空格」以及「花括号」的位置。
<?php
$closureWithArgs = function ($arg1, $arg2) {
      // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
      // body
};

参数列表以及变量列表 可以 分成多行,这样,包括第一个在内的每个参数或变量都 必须 单独成行,而列表的右括号与闭包的开始花括号 必须 放在同一行。以下几个例子,包含了参数和变量列表被分成多行的多情况。

<?php
$longArgs_noVars = function (
      $longArgument,
      $longerArgument,
      $muchLongerArgument
) {
      // body
};

$noArgs_longVars = function () use (
      $longVar1,
      $longerVar2,
      $muchLongerVar3
) {
      // body
};

$longArgs_longVars = function (
      $longArgument,
      $longerArgument,
      $muchLongerArgument
) use (
      $longVar1,
      $longerVar2,
      $muchLongerVar3
) {
      // body
};

$longArgs_shortVars = function (
      $longArgument,
      $longerArgument,
      $muchLongerArgument
) use ($var1) {
      // body
};

$shortArgs_longVars = function ($arg) use (
      $longVar1,
      $longerVar2,
      $muchLongerVar3
) {
      // body
};

注意,闭包被直接用作函数或方法调用的参数时,以上规则仍然适用。

<?php
$foo->bar(
      $arg1,
      function ($arg2) use ($var1) {
            // body
      },
      $arg3
);

本规范仅为本人习惯,有遗漏后续再更新。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 211,884评论 6 492
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 90,347评论 3 385
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 157,435评论 0 348
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 56,509评论 1 284
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 65,611评论 6 386
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 49,837评论 1 290
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,987评论 3 408
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 37,730评论 0 267
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 44,194评论 1 303
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 36,525评论 2 327
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 38,664评论 1 340
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 34,334评论 4 330
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,944评论 3 313
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,764评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,997评论 1 266
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 46,389评论 2 360
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 43,554评论 2 349

推荐阅读更多精彩内容