PHP开发规范

最新推荐文章于 2024-03-18 09:58:54 发布

原创最新推荐文章于 2024-03-18 09:58:54 发布 · 334 阅读

3 ·

CC 4.0 BY-SA版权

Web开发专栏收录该内容

5 篇文章

订阅专栏

PHP开发规范

版本：V1.0.0

文章目录

PHP开发规范

1 开篇

本规范希望通过制定一系列规范化PHP代码的规则，以减少在浏览不同作者的代码时，因代码风格的不同而造成不便。

当多名程序员在多个项目中合作时，就需要一个共同的编码规范，而本文中的风格规范源自于多个不同项目代码风格的共同特性，因此，本规范的价值在于我们都遵循这个编码风格，而不是在于它本身。

1.1 参考

PSR-1 http://www.php-fig.org/psr/psr-1/
PSR-2 http://www.php-fig.org/psr/psr-2/

2 文件

2.1 PHP标签

PHP代码必须使用 <?php ?> 长标签，一定不可使用其它自定义标签。

2.2 字符编码

PHP代码必须且只可使用不带BOM的UTF-8编码。

3 命名

3.1 变量

3.1.1 普通变量

普通变量命名必须符合小写开头的驼峰式 ($camelCase)命名规范。

3.1.2 全局变量

全局变量命名必须符合 StudlyCaps大写开头的驼峰命名规范，并在首字母前加一个字符:“g”，以标识其为全局变量。

3.2 常量

常量命名采用必须全用大写的字母，用下划线分割单词。命名应能清晰表名意义。例如:

define('VERSION', '8.0,20100530');

晦涩难懂、难记忆的值用常量代替。例如: 1 代表投票，2 代表另一种帖子类型;应定义常量:

define("PW_THREAD_TYPE_VOTE", 1);

3.3 函数

函数命名必须符合小写开头的驼峰式 ($camelCase)命名规范

3.4 类命名

3.4.1 类名称

每个类都独立为一个文件

3.4.2 类的常量

类的常量中所有字母都必须大写，单词间以下划线分隔。
参照以下代码：

<?php
namespace Vendor\Model;

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

3.4.3 类的属性

类的属性命名必须符合小写开头的驼峰式 ($camelCase)命名规范。

3.4.4 类的方法

方法名称必须符合 camelCase() 式的小写开头驼峰命名规范。

4 代码规则

4.1 文件

所有PHP文件必须使用Unix LF (linefeed)作为行的结束符
所有PHP文件必须以一个空白行作为结束
纯PHP代码文件必须省略最后的 ?> 结束标签
PHP起始标签的前面和结束标签的后面都不要留空格，如果你的文件中有空格的话，这些空格会在输出它的内容之前被输出，从而会导致无法发送正确的头信息

4.2 行

行的长度一定不能有硬性的约束
每行不应该多于120个字符，大于120字符的行应该折成多行
非空行后一定不能有多余的空格符
空行可以使得阅读代码更加方便以及有助于代码的分块
每行一定不能多于一条PHP语句

4.3 缩进

代码必须使用4个空格符的缩进，一定不能用Tab键

备注:

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

4.4 关键字

PHP所有关键字必须全部小写。

4.5 类、属性和方法

4.5.1 继承与实现

关键词 extends 和 implements必须写在类名称的同一行。

类的开始花括号必须独占一行，结束花括号也必须在类主体后独占一行。

<?php
namespace Vendor\Package;

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

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // constants, properties, methods
}

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

<?php
namespace Vendor\Package;

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

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // constants, properties, methods
}

4.5.2 属性

每个属性都必须添加访问修饰符public、protected 或 private。

一定不可使用关键字 var 声明一个属性。

每条语句一定不可定义超过一个属性。

不要使用下划线作为前缀来区分属性是 protected 或 private。

以下是属性声明的一个范例：

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.5.3 方法

建议所有方法都添加访问修饰符public、protected 或 private。

不要使用下划线作为前缀，来区分方法是 protected 或 private。

方法名称后一定不能有空格符，其开始花括号必须独占一行，结束花括号也必须在方法主体后单独成一行。参数左括号后和右括号前一定不能有空格。

一个标准的方法声明可参照以下范例，留意其括号、逗号、空格以及花括号的位置。

<?php
namespace Vendor\Package;

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

4.5.4 方法的参数

参数列表中，每个逗号后面必须要有一个空格，而逗号前面一定不能有空格。

有默认值的参数，必须放到参数列表的末尾。

<?php
namespace Vendor\Package;

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

参数列表可以分列成多行，这样，包括第一个参数在内的每个参数都必须单独成行。

拆分成多行的参数列表后，结束括号以及方法开始花括号必须写在同一行，中间用一个空格分隔。

<?php
namespace Vendor\Package;

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

适当的时候，提供函数参数的缺省值，这有助于防止因错误的函数调用引起的PHP错误，另外提供常见的备选值可以节省几行代码。例如:

function foo($bar = '', $baz = FALSE)

4.5.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.5.6 方法及函数调用

方法及函数调用时，方法名或函数名与参数左括号之间一定不能有空格，参数右括号前也 一定不能有空格。每个逗号前一定不能有空格，但其后必须有一个空格。

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

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

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

4.6 字符串

字符串使用单引号引起来，当字符串中有变量时使用双引号，并且使用大括号将变量包起来。另外，当字符串中有单引号时，也应该使用双引号，这样就不用使用转义符。

错误的

"My String"                 //无变量，应使用单引号
"My string $foo"                //需要用大括号
'SELECT foo FROM bar WHERE baz = \'bag\''   //应该使用双引号

正确的

'My String'
"My string {$foo}"
"SELECT foo FROM bar WHERE baz = 'bag'"

4.7 SQL查询

SQL 关键字永远使用大写：SELECT、INSERT、UPDATE、WHERE、AS、JOIN、ON、IN 等。

考虑到易读性，把长的查询分成多行，最好是每行只有一个从句或子从句。

错误的


$query = $this->db->query("select foo, bar, baz, foofoo, foobar as raboof, foobaz from exp_pre_email_addresses
...where foo != 'oof' and baz != 'zab' order by foobaz limit 5, 100");

正确的

$query = $this->db->query("SELECT foo, bar, baz, foofoo, foobar AS raboof, foobaz
                FROM exp_pre_email_addresses
                WHERE foo != 'oof'
                AND baz != 'zab'
                ORDER BY foobaz
                LIMIT 5, 100");

4.8 PHP 错误

运行代码时不应该出现任何错误信息，并不是把警告和提示信息关掉来满足这一点。例如，绝不要直接访问一个你没设置过的变量，你应该先使用 isset() 函数判断下。

函数和方法的行数限制

函数和方法的代码限制在80行之内

5 控制结构

控制结构的基本规范如下：

控制结构关键词后必须有一个空格。
左括号 ( 后一定不能有空格。
右括号 ) 前也一定不能有空格。
右括号 ) 与开始花括号 { 间一定有一个空格。
结构体主体一定要有一次缩进。
结束花括号 } 一定在结构体主体后单独成行。

每个结构体的主体都必须被包含在成对的花括号之中，这能让结构体更加结构话，以及减少加入新行时，出错的可能性。

5.1. `if` 、 `elseif` 和 `else`

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

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

应该使用关键词 elseif 代替所有 else if ，以使得所有的控制关键字都像是单独的一个词。

5.2. `switch` 和 `case`

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

<?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
}

5.6 对返回值进行比较

有一些 PHP 函数在失败时返回 FALSE ，但是也可能会返回 “” 或 0 这样的有效值，这些值在松散类型比较时和 FALSE 是相等的。所以当你在条件中使用这些返回值作比较时，一定要使用严格类型比较，确保返回值确实是你想要的，而不是松散类型的其他值。

在检查你自己的返回值和变量时也要遵循这种严格的方式，必要时使用 === 和 !== 。

错误

// 如果 'foo' 在字符串的开始，函数strpos会返回0，表达式的结果是TRUE，显然不是我们要的结果
if (strpos($str, 'foo') == FALSE)

正确

if (strpos($str, 'foo') === FALSE)

错误的:

function buildString($str = "")
{
    //如果调用函数时传入的参数是0或者FALSE会怎么样？
    if ($str == "") 
    {

    }
}

正确的:

function buildString($str = "")
{
    if ($str === "")
    {

    }
}

5.7 闭包

闭包声明时，关键词 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
);

6 注释

通常情况下，应该多写点注释，这不仅可以向其他的程序员描述代码的流程和意图，而且当你几个月后再回过头来看自己的代码时仍能帮你很好的理解代码。

公共函数、类库、全局变量等必须提供详细的注释说明。

6.1 代码注释

6.1.1 普通注释

普通注释严格按照 phpDocumentor 的标准，基本上所有类型的注释都有规定。官方文档: http://manual.phpdoc.org/HTMLframesConverter/default/。

下面列出主要几种注释的规则。 phpdoc 注释，主要有三个基础部分:

/**
 * Short Description
*
 * Long Description
*
* Tags */

短描述起始于第一行，以一个空行或句点结束，如果超过三行则取第一行。长描述可以任意长。

长短描述中，可以使用一些简单的 html 标签，如:<p> <pre> <b> <code> <br> <li> <ul>，会在phpdoc生成文档时解析。

标签是一个带有@符号的单词，标签是可选的。

6.1.2 片段注释

片段注释，需要标识逻辑片段的开头和结尾，格式为:

/*--- 说明文字 ---start*/ 
$tmp = $varA;
$varA = $varB;
$varB = $tmp; 
/*---说明文字 ---end*/

6.1.3 行逻辑注释

行逻辑注释(这里是指对一行的逻辑进行注释，变量声明等还是使用 phpdoc 的注释方法)，使用//的方式，放在程序语句的后面，例如:

updateOnline(); // 更新在线用户

6.2 函数注释

函数注释:短描述必填，如有则必须填写这些标签 @global @param @return，其他可选。
例如:

/**
 * 针对SQL语句的变量进行反斜线过滤,并两边添加单引号
 * @param mixed $var 过滤前变量
 * @param boolean $strip 数据是否经过stripslashes处理
 * @param boolean $is_array 变量是否为数组 
 * @return mixed 过滤后变量
 */
function sqlQoute($var, $strip = true, $isArray = false) {
    ... 
}

6.3 类注释

类注释:短描述必填，@package、@author 等可选。
例如：

/**
 * short desc 
 *
 * long desc
 * @package test 
 * @author me
 * @abstract
 */

class My_Class {
}

类的属性的注释:短描述必填，@var 标签必填，@access 为非 public 时必填。类的方法的注释和函数一样。

例如:


class My_Class{ 

/**
 * example of documenting a variable's type 
 * @var string
 */
  private $variable;

  /**
   * a static method 
   * @static
   */
  function myStaticMethod() {
  }

  /**
   * normal method
   */
  function myNormalMethod() {
  }

  /**
   * protected method 
   * @access protected 
   */
  function protectedMethod() {
  }

}

6.4 文件注释

文件注释:短描述必填，@package 可选，文件注释放在文件开头。
例如：


<?php
/**
 * Page-Level DocBlock example.
 * This DocBlock precedes another DocBlock and will be parsed as the 
 * page-level.
 * Put your @package and @subpackage tags here 
 * @package pagelevel_package
 */

/**
 * function bluh
 */
function bluh() {
}