B.1. 绪论
对于只包含有 PHP 代码的文件,结束标志("?>")是不允许存在的,PHP自身不需要("?>"), 这样做, 可以防止它的末尾的被意外地注入空白并显示输出。
重要: 由 __HALT_COMPILER()
允许的任意的二进制代码的内容被 Zend Framework PHP 文件或由它们产生的文件禁止。这个功能的使用只对特殊的安装脚本开放。
Zend Framework 的类命名总是对应于其所属文件的目录结构的,Zend Framework 的根目录是 “Zend/”,所有的类在其下按等级存放。
类名只允许有字母数字字符,但不鼓励使用数字。下划线只允许做路径分隔符,例如 Zend/Db/Table.php 文件里对应的类名称是 Zend_Db_Table。
如果类名包含多个单词,每个单词的第一个字母必须大写,连续的大写是不允许的,例如 “Zend_PDF” 是不允许的,而 "Zend_Pdf" 是可接受的。
由 Zend 或其参与 Zend Framework 项目的伙伴公司发行的类必须以 "Zend_" 开头并且必须按等级放在 "Zend/"目录下。
可接受的类名的例子:
Zend_Db Zend_View Zend_View_Helper
重要: 最终用户写的代码,不要以 "Zend_" 开头。
接口类也必须遵循同样的约定(如上所述),但必须以 "Interface" 结尾,比如这些例子:
Zend_Log_Adapter_Interface Zend_Controller_Dispatcher_Interface
对于其它文件,只有字母数字字符、下划线和短横线("-")可用,空格是不允许的。
包含任何 PHP 代码的任何文件必须以 ".php" 扩展名结尾。这些例子给出可接受的文件名,它们包含的类名都在上述章节的例子中:
Zend/Db.php Zend/Controller/Front.php Zend/View/Helper/FormRadio.php
文件名必须遵循上述的对应类名的规则。
函数名只包含字母数字字符,但不鼓励使用数字,下划线是不允许的。
函数名总是以小写开头,当函数名包含多个单词,每个子的首字母必须大写,这就是所谓的 “驼峰” 格式。
我们鼓励使用冗长的名字,这样容易理解代码。
这些是可接受的函数名的例子:
filterInput() getElementById() widgetFactory()
对于面向对象编程,对象的访问器总是以 "get" 或 "set" 为前缀。当使用设计模式如 单态模式(singleton)或工厂模式(factory),方法的名字应当包含模式的名字,这样容易从名字识别设计模式。
在对象中的方法,声明为 "private" 或 "protected" 的, 名称的首字符必须是一个单个的下划线,这是唯一的下划线在方法名字中的用法。声明为 "public" 的从不以下划线开头。
全局函数 ("floating functions") 允许但不鼓励,建议把这类函数封装到静态类里。
变量只包含数字字母字符,不鼓励使用数字,下划线不接受。
声明为 "private" 或 "protected" 的类成员变量名必须以一个单个下划线开头,这是唯一的下划线在变量名中的用法,声明为 "public" 的从不以下划线开头。
象函数名(见上面 3.3 节)一样,变量名总以小写字母开头并遵循“驼峰式”命名约定。
我们鼓励使用冗长的名字,这样容易理解代码。除非在小循环里,不鼓励使用简洁的名字如 "$i" 和 "$n" 。如果一个循环超过 20 行代码,索引的变量名必须有个具有描述意义的名字。
当文字字符串包含单引号(apostrophe )就用双引号括起来,特别在 SQL 语句中:
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
在转义单引号时,上述语法是首选的。
变量替换有下面两种形式:
$greeting = "Hello $name, welcome back!"; $greeting = "Hello {$name}, welcome back!";
为保持一致,这个形式不允许:
$greeting = "Hello ${name}, welcome back!";
索引不能为负数
建议数组索引从 0 开始。
当用 array
声明有索引的数组,在每个逗号的后面价格空格以提高可读性:
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
也可以用 "array" 声明多行有索引的数组,在每个连续行的开头要用空格填补对齐:
$sampleArray = array(1, 2, 3, 'Zend', 'Studio', $a, $b, $c, 56.44, $d, 500);
用下面的约定来命名类。
花括号总是从类名下一行开始。
每个类必须有一个符合 PHPDocumentor 标准的文档块。
四个空格的缩进。
每个 PHP 文件中只有一个类。
放另外的代码到类里允许但不鼓励。在这些文件中,用两行空格来分隔类和其它代码。
这是个可接受的类的例子:
/** * Documentation Block Here */ class SampleClass { // entire content of class // must be indented four spaces }
必须用下面的变量名约定来命名函数。
在类中的函数必须用 private
、 protected
或 public
声明它们的可见性。
象类一样,花括号从函数名的下一行开始,函数名和括参数的圆括号中间没有空格。
强烈反对使用全局函数。
可接受的在类中的函数声明的例子:
/** * Documentation Block Here */ class Foo { /** * Documentation Block Here */ public function bar() { // entire content of function // must be indented four spaces } }
注: 传址(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; } }
使用 if
and elseif
的控制语句在条件语句的圆括号前后都必须有一个空格。
在圆括号里的条件语句,操作符必须用空格分开,鼓励使用多重圆括号以提高在复杂的条件中划分逻辑组合。
前花括号必须和条件语句在同一行,后花括号单独在最后一行,其中的内容用四个空格缩进。
if ($a != 2) { $a = 2; }
下面的例子示例 "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" 组合。
在 "switch" 结构里的控制语句在条件语句的圆括号前后必须都有一个单个的空格。
"switch" 里的代码必须有四个空格缩进,在"case"里的代码再缩进四个空格。
switch ($numPeople) { case 1: break; case 2: break; default: break; }
switch
语句中必须有 default
。
注: 有时候,在 falls through 到下个 case 的 case
语句中不写 break
or return
很有用。为了区别于 bug,任何 case
语句中,所有不写 break
or return
的地方必须有 "// break intentionally omitted" 这样的注释。
所有文档块 ("docblocks") 必须和 phpDocumentor 格式兼容,phpDocumentor 格式的描述超出了本文档的范围,关于它的详情,参考:http://phpdoc.org/。
所有 Zend Framework 或和它一起工作的源代码必须在每个文件的顶部包含文件级 ("file-level")的 docblock ,在每个类的顶部放置一个 "class-level" 的 docblock。下面是一些例子:
每个包含 PHP 代码的文件必须至少在文件顶部包含这些 phpDocumentor 标签:
/** * 文件的简短描述 * * 文件的详细描述(如果有的话)... ... * * LICENSE: 一些 license 信息 * * @copyright 2005 Zend Technologies * @license http://www.zend.com/license/3_0.txt PHP License 3.0 * @version $Id:$ * @link http://dev.zend.com/package/PackageName * @since File available since Release 1.2.0 */
每个类必须至少包含这些 phpDocumentor 标签:
/** * 类的简述 * * 类的详细描述 (如果有的话)... ... * * @copyright 2005 Zend Technologies * @license http://www.zend.com/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://dev.zend.com/package/PackageName * @since Class available since Release 1.2.0 * @deprecated Class deprecated in Release 2.0.0 */