php编码规范

阅读更多

B.4. 编码风格
B.4. 编码风格 ¶
B.4.1. PHP 代码划分（Demarcation） ¶

PHP 代码总是用完整的标准的 PHP 标签定界：


?>

短标签 是不允许的，只包含 PHP 代码的文件，不要结束标签 （参见 [ http://trac.lebwork.org/coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.general 第 B.2.1 节 “ 常规 ”]）。
B.4.2. 字符串 ¶
B.4.2.1. 字符串文字 ¶

当字符串是文字(不包含变量)，应当用单引号（ apostrophe ）来括起来：

$a = 'Example String';
                   

B.4.2.2. 包含单引号（'）的字符串文字 ¶

当文字字符串包含单引号（apostrophe ）就用双引号括起来，特别在 SQL 语句中有用：

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
                   

在转义单引号时，上述语法是首选的，因为很容易阅读。
B.4.2.3. 变量替换 ¶

变量替换有下面这些形式：

$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
                   

为保持一致，这个形式不允许：

$greeting = "Hello ${name}, welcome back!";
                   

B.4.2.4. 字符串连接 ¶

字符串必需用 "." 操作符连接，在它的前后加上空格以提高可读性：

$company = 'Zend' . ' ' . 'Technologies';
                   

当用 "." 操作符连接字符串，鼓励把代码可以分成多个行，也是为提高可读性。在这些例子中，每个连续的行应当由 whitespace 来填补，例如 "." 和 "=" 对齐：

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
                   

B.4.3. 数组 ¶
B.4.3.1. 数字索引数组 ¶

索引不能为负数

建议数组索引从 0 开始。

当用array函数声明有索引的数组，在每个逗号的后面间隔空格以提高可读性：

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
                   

可以用 "array" 声明多行有索引的数组，在每个连续行的开头要用空格填补对齐：

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
                   

B.4.3.2. 关联数组 ¶

当用声明关联数组，array我们鼓励把代码分成多行，在每个连续行的开头用空格填补来对齐键和值：

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
                   

B.4.4. 类 ¶
B.4.4.1. 类的声明 ¶

用 Zend Framework 的命名约定来命名类。

花括号应当从类名下一行开始(the "one true brace" form)。

每个类必须有一个符合 PHPDocumentor 标准的文档块。

类中所有代码必需用 Tab 键进行缩进。

每个 PHP 文件中只有一个类。

放另外的代码到类里允许但不鼓励。在这样的文件中，用两行空格来分隔类和其它代码。

下面是个可接受的类的例子： // 459 9506 － 441 9658 下次从这里开始

/**
* Documentation Block Here
*/
class SampleClass
{
    // 类的所有内容
    // 必需缩进Tab 键进行
}
                   

B.4.4.2. 类成员变量 ¶

必须用Zend Framework的变量名约定来命名类成员变量。

变量的声明必须在类的顶部，在方法的上方声明。

不允许使用var（因为 ZF 是基于 PHP 5 的 ），要用private、protected或public。 直接访问 public 变量是允许的但不鼓励，最好使用访问器 （set/get）。
B.4.5. 函数和方法 ¶
B.4.5.1. 函数和方法声明 ¶

必须用Zend Framework的函数名约定来命名函数。

在类中的函数必须用private、protected或public声明它们的可见性。

象类一样，花括号从函数名的下一行开始(the "one true brace" form)。

函数名和括参数的圆括号中间没有空格。

强烈反对使用全局函数。

下面是可接受的在类中的函数声明的例子：

/**
* Documentation Block Here
*/
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // 函数的所有内容
        // 必需缩进Tab 键进行
    }
}
                   

注： 传址（Pass-by-reference）是在方法声明中允许的唯一的参数传递机制。

/**
* Documentation Block Here
*/
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar(&$baz)
    {}
}
                   

传址在调用时是严格禁止的。

返回值不能在圆括号中，这妨碍可读性而且如果将来方法被修改成传址方式，代码会有问题。

/**
* Documentation Block Here
*/
class Foo
{
    /**
     * WRONG
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RIGHT
     */
    public function bar()
    {
        return $this->bar;
    }
}
                   

B.4.5.2. 函数和方法的用法 ¶

函数的参数应当用逗号和紧接着的空格分开，下面可接受的调用的例子中的函数带有三个参数：

threeArguments(1, 2, 3);
                   

传址方式在调用的时候是严格禁止的，参见函数的声明一节如何正确使用函数的传址方式。

带有数组参数的函数，函数的调用可包括 "array" 提示并可以分成多行来提高可读性，同时，书写数组的标准仍然适用：

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);
                   

B.4.6. 控制语句 ¶
B.4.6.1. if/Else/Elseif ¶

使用ifandelseif的控制语句在条件语句的圆括号前后都必须有一个空格。

在圆括号里的条件语句，操作符必须用空格分开，鼓励使用多重圆括号以提高在复杂的条件中划分逻辑组合。

前花括号必须和条件语句在同一行，后花括号单独在最后一行，其中的内容用Tab 键进行缩进。

if ($a != 2) {
    $a = 2;
}
                   

对包括"elseif" 或 "else"的 "if" 语句，和 "if" 结构的格式类似， 下面的例子示例 "if" 语句， 包括 "elseif" 或 "else" 的格式约定：

if ($a != 2) {
    $a = 2;
} else {
   $a = 7;
}


if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
   $a = 4;
} else {
   $a = 7;
}
                   

在有些情况下， PHP 允许这些语句不用花括号，但在(ZF) 代码标准里，它们（"if"、 "elseif" 或 "else" 语句）必须使用花括号。

"elseif" 是允许的但强烈不鼓励，我们支持 "else if" 组合。
B.4.6.2. Switch ¶

在 "switch" 结构里的控制语句在条件语句的圆括号前后必须都有一个单个的空格。

"switch" 里的代码必须有Tab键缩进，在"case"里的代码再缩进Tab 键进行。

switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
               

switch语句应当有default。

注： 有时候，在 falls through 到下个 case 的case语句中不写breakorreturn很有用。 为了区别于 bug，任何case语句中，所有不写breakorreturn的地方应当有一个 "// break intentionally omitted" 这样的注释来表明 break 是故意忽略的。
B.4.7. 注释文档 ¶
B.4.7.1. 格式 ¶

所有文档块 ("docblocks") 必须和 phpDocumentor 格式兼容，phpDocumentor 格式的描述超出了本文档的范围，关于它的详情，参考： http://phpdoc.org/。

所有类文件必须在文件的顶部包含文件级 （"file-level"）的 docblock ，在每个类的顶部放置一个 "class-level" 的 docblock。下面是一些例子：
B.4.7.2. 文件 ¶

每个包含 PHP 代码的文件必须至少在文件顶部的 docblock 包含这些 phpDocumentor 标签：

/**
* 文件的简短描述
*
* 文件的详细描述（如果有的话）... ...
*
* LICENSE: 一些 license 信息
*
* @copyright  2008 Zend Technologies
* @license    http://framework.zend.com/license/3_0.txt   BSD License
* @version    $Id:$
* @link       http://framework.zend.com/package/PackageName
* @since      File available since Release 1.5.0
*/
                   

B.4.7.3. 类 ¶

每个类必须至少包含这些 phpDocumentor 标签：

/**
* 类的简述
*
* 类的详细描述 （如果有的话）... ...
*
* @copyright  2008 Zend Technologies
* @license    http://framework.zend.com/license/   BSD License
* @version    Release: @package_version@
* @link       http://framework.zend.com/package/PackageName
* @since      Class available since Release 1.5.0
* @deprecated Class deprecated in Release 2.0.0
*/
                   

B.4.7.4. 函数 ¶

每个函数，包括对象方法，必须有最少包含下列内容的文档块（docblock）：

    * 函数的描述

    * 所有参数

    * 所有可能的返回值

因为访问级已经通过 "public"、 "private" 或 "protected" 声明， 不需要使用 "@access"。

如果函数/方法抛出一个异常，使用 @throws 于所有已知的异常类：