PHPファイルのファイル形式

PHP ファイル形式

PHP コードのみを含むファイルの場合、終了マーク ("?>") は存在できません。これを行うと、PHP 自体がそれを防ぐことができます。対応する端が誤って注入されました。

重要: __HALT_COMPILER() によって許可される任意のバイナリ コード コンテンツは、Zend Framework の PHP ファイル、または Zend Framework によって生成されるファイルによって禁止されています。 この機能は一部のインストール スクリプトでのみ使用できます。

インデントは 4 つのスペースで構成され、タブ文字 TAB は禁止されています。

行の最大長

1 行は 80 文字未満であることがより適切です。つまり、ZF 開発者は、コードの各行を可能な限り 80 文字未満に抑えるよう努める必要があります。ただし、制限は 120 文字です。

行末フラグ

行末フラグは Unix テキスト ファイルの規則に従い、行は 1 つの改行文字 (LF) で終わる必要があります。改行文字は、ファイル内では 10、つまり 16 進数の 0x0A として表されます。

注: Apple オペレーティング システムのキャリッジ リターン (0x0D)、または Windows コンピュータのキャリッジ リターンとライン フィードの組み合わせ (0x0D、0x0A) などは使用しないでください。

命名規則

Zend Framework クラスの命名は、常に、それが属するファイルのディレクトリ構造に対応します。ZF 標準ライブラリのルート ディレクトリは「Zend/」で、ZF スペシャル ライブラリのルート ディレクトリは「Zend/」です。追加) ライブラリは "ZendX /" で、すべての Zend Framework クラスはその下に階層的に格納されます。

クラス名には英数字のみが使用でき、ほとんどの場合、数字の使用は推奨されません。アンダースコアはパス区切り文字としてのみ使用できます。たとえば、Zend/Db/Table.php ファイル内の対応するクラス名は Zend_Db_Table です。

クラス名に複数の単語が含まれる場合、各単語の最初の文字を連続して大文字にすることは許可されません。たとえば、「Zend_PDF」は許可されます。

これらの規則は、Zend Framework の擬似名前空間メカニズムを定義します。 Zend Framework は、開発者がプロ​​グラムに実装できる場合、PHP 名前空間機能を採用します。

標準および特殊ライブラリのクラス名規則の例を参照してください。重要: ZF ライブラリ拡張に依存しているが、標準ライブラリまたは特殊ライブラリの一部ではないコード (Zend によって配布されていないプログラム コードやライブラリなど) は、「Zend_」または「ZendX_」で始めないでください。

ファイル名

その他のファイルには、英数字、アンダースコア、ダッシュ (「-」) のみを使用できます。スペースは絶対に使用できません。

よく知られているビュー スクリプトを除き、PHP コードを含むファイルはすべて「.php」拡張子で終わる必要があります。次の例は、Zend Framework クラスで使用できるファイル名を示しています。

Zend/Db.phpZend/Controller/Front.phpZend/View/Helper/FormRadio.php                

ファイル名は、上記の対応するクラス名の規則に従う必要があります。

関数とメソッド

関数名には英数字のみを使用でき、アンダースコアは使用できません。数値は許可されていますが、ほとんどの場合推奨されません。

関数名は常に小文字で始まります。関数名に複数の単語が含まれる場合、各サブワードの最初の文字を大文字にする必要があります。これは、いわゆる「キャメルケース」形式です。

一般に長い名前を使用することをお勧めします。関数名は、関数の意図と動作を説明するのに十分な長さである必要があります。

以下は許容される関数名の例です:

filterInput()getElementById()widgetFactory()                

オブジェクト指向プログラミングでは、インスタンスや静的変数などのアクセサーには常に "get" または "set" というプレフィックスが付けられます。シングルトンやファクトリなどのデザイン パターンの実装に関しては、名前で動作全体をより適切に説明できるように、メソッドの名前にパターンの名前を含める必要があります。

「private」または「protected」として宣言されたオブジェクト内のメソッドの場合、名前の最初の文字は 1 つのアンダースコアである必要があります。メソッド名でのアンダースコアの使用はこれのみです。 「public」としての宣言にはアンダースコアが含まれることはありません。

グローバル関数 (「浮動関数」など) は許可されますが、ほとんどの場合推奨されません。そのような関数を静的クラスにカプセル化することをお勧めします。

変数には英数字のみが含まれます。ほとんどの場合、数字は推奨されず、アンダースコアは受け入れられません。

「private」または「protected」として宣言されたインスタンス変数名は、単一のアンダースコアで始まる必要があります。「public」として宣言されたインスタンス変数の名前は、プログラム内でアンダースコアを使用する唯一の使用法です。 。

関数名 (上記のセクション 3.3 を参照) と同様に、変数名は常に小文字で始まり、「キャメルケース」の命名規則に従います。

我们一般鼓励使用冗长的名字，这样容易理解代码，开发者知道把数据存到哪里。除非在小循环里，不鼓励使用简洁的名字如 "$i" 和 "$n" 。如果一个循环超过 20 行代码，索引的变量名必须有个具有描述意义的名字。

常量包含数字字母字符和下划线，数字允许作为常量名。

常量名的所有字母必须大写。

常量中的单词必须以下划线分隔，例如可以这样 EMBED_SUPPRESS_EMBED_EXCEPTION 但不许这样EMBED_SUPPRESSEMBEDEXCEPTION。

常量必须通过 "const" 定义为类的成员，强烈不鼓励使用 "define" 定义的全局常量。

 

编码风格

PHP 代码划分（Demarcation）

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

<?php?>

 

短标签（ ）是不允许的，只包含 PHP 代码的文件，不要结束标签 （参见 常规）。

字符串

字符串文字

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

$a = 'Example String';                    

 

包含单引号（'）的字符串文字

当文字字符串包含单引号（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!";                    

 

字符串连接

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

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

 

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

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

 

数字索引数组

索引不能为负数

建议数组索引从 0 开始。

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

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

 

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

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

 

关联数组

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

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

 

类的声明

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

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

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

类中所有代码必需用四个空格的缩进。

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

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

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

/** * Documentation Block Here */class SampleClass{    // 类的所有内容    // 必需缩进四个空格}                    

 

类成员变量

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

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

不允许使用 var （因为 ZF 是基于 PHP 5 的 ），要用 private、 protected 或 public。 直接访问 public 变量是允许的但不鼓励，最好使用访问器 （set/get）。

函数和方法

函数和方法声明

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

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

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

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

强烈反对使用全局函数。

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

/** * Documentation Block Here */class Foo{    /**     * Documentation Block Here     */    public function bar()    {        // 函数的所有内容        // 必需缩进四个空格    }}                    

 

注： 传址（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;    }}                    

 

函数和方法的用法

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

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);                    

 

控制语句

if/Else/Elseif

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

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

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

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" 组合。

Switch

在 "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" 这样的注释来表明 break 是故意忽略的。

注释文档

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

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

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

/** * 文件的简短描述 * * 文件的详细描述（如果有的话）... ... * * LICENSE: 一些 license 信息 * * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com) * @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*/                    

 

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

/** * 类的简述 * * 类的详细描述 （如果有的话）... ... * * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com) * @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 */                    

 

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

函数的描述

所有参数

所有可能的返回值

 

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

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

@throws exceptionclass [description]                    

来源：http://framework.zend.com/manual/zh/coding-standard.php-file-formatting.html