PHPコーディング標準

编码|规范

缩进

缩进使用4个空格，而不是 tab。如果你使用 Emacs 编辑 PEAR 代码，你应该设置 indent-tabs-mode 为 nil。下面是一个 mode hook 的示例，用于设置 Emacs 符合缩进标准（你必须确保在编辑 PHP 文件时，这些设置发生作用）：

  (defun php-mode-hook ()
  (setq tab-width 4
        c-basic-offset 4
        c-hanging-comment-ender-p nil
        indent-tabs-mode
        (not
         (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
              (string-match "\.php$" (buffer-file-name))))))

这里是同等效果的 vim 规则：

  set expandtab
  set shiftwidth=4
  set softtabstop=4
  set tabstop=4

--------------------------------------------------------------------------------

控制结构

控制结构包含 if、for、while、switch 等。这里有一个 if 语句的示例和一个 switch 语句的示例：

if 语句的示例：

if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
?>

switch 语句的示例：

switch (condition) {
case 1:
action1;
break;
case 2:
action2;
break;
default:
defaultaction;
break;
}
?>

控制语句应该在控制关键词和开始的圆括号之间应该有一个空格，以此和函数调用进行区别。

强烈建议你总是使用花括号将控制结构各部分标识出来。即使是在技术上可以不使用花括号的地方。这可以增加代码的可读性，同时避免在结构部分增加新行后引入逻辑上的错误。

原始代码：

if (condition)
    return true;
else
    return false;

修改后的代码：

if (condition)
    do something; // 出现逻辑错误
    return true;
else
    return false;

正确的做法：

if (condition) {
    do something;
    return true;
} else {
    return false;
}

--------------------------------------------------------------------------------

函数调用

调用函数时，函数名和开始的括号之间不应该有空白字符。参数和开始及结束的括号之间不应有空格。而除第一个参数外，其他参数都应该用一个空格分隔。这里有一个示例：

$var = foo($bar, $baz, $quux);
?>

像上面的示例代码，赋值运算等号两边都应该使用一个空格。如果是相关的赋值运算，应该采用下面的形式以提供更好的可读性：

$short = foo($bar);
$long_variable = foo($baz);
?>

--------------------------------------------------------------------------------

函数定义

按照“one true brace”约定声明函数：

function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}
?>

“one true brace”约定就是开始的花括号单独占一行，而不是跟在其他语句后面。

具有默认值的参数应该位于参数列表的后面（事实上 PHP 语言定义也要求如此）。如果适合，函数应该总是返回一个有意义的值。这里有一个稍微长一点的示例：

function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
    }
    return true;
}
?>

--------------------------------------------------------------------------------

注释

类型（class）的联机文档应该符合 PHPDoc（类似于 JavaDoc）的约定。更多关于 PHPDoc 的信息可以访问 http://www.phpdoc.de/ 获得。

此外，强烈鼓励使用非文档注释。一般性规则是对于那些容易忘记作用的代码添加简短的介绍性注释。

推荐使用 C 样式的注释（/* */）和标准 C++ 注释（//)，而不应该使用 Perl/shell 样式的注释（#）。

--------------------------------------------------------------------------------

包含代码

无论在什么地方无条件包含一个类型文件，应该使用 require_once()。如果有条件的包含一个类型文件（例如使用工厂方法），应该使用 include_once()。使用两者中的任何一个都能够确保类型文件只包含一次。它们共享一个文件列表，因此你不需要担心混淆他们 —— 一个文件使用 require_once() 包含后不会在 include_once() 中再一次被包含。

备注：include_once() 和 require_once() 是一个声明，而不是函数。你不需要使用圆括号将文件名扩起来（不过使用括号也不会出现错误）。

--------------------------------------------------------------------------------

PHP 代码标记

总是使用 来界定 PHP 代码，而不要使用 速记方式。这是为了符合 PEAR 一致性所必须的，同时也是在不同操作系统和不同安装设置环境下移植 PHP 代码所要求的。

--------------------------------------------------------------------------------

头注释块

PEAR 发布的所有源代码文件头部都应该包含下面的注释块：

/* vim: set expandtab tabstop=4 softtabstop=4 shiftwidth=4: */
// +----------------------------------------------------------------------+
// | PHP version 4 |
// +----------------------------------------------------------------------+
// | Copyright (c) 1997-2002 The PHP Group |
// +----------------------------------------------------------------------+
// | This source file is subject to version 2.0 of the PHP license, |
// | that is bundled with this package in the file LICENSE, and is |
// | available at through the world-wide-web at |
// | http://www.php.net/license/2_02.txt. |
// | If you did not receive a copy of the PHP license and are unable to |
// | obtain it through the world-wide-web, please send a note to |
// | license@php.net so we can mail you a copy immediately. |
// +----------------------------------------------------------------------+
// | Authors: Original Author                         |
// | Your Name                                           |
// +----------------------------------------------------------------------+
//
// $ Id $
?>

这里没有硬性规定要将一个代码贡献者的名字添加到文件注释的作者列表中。一般情况下，他们的更改属于“substantial”目录（意味大约10%到20%的代码被改写）。有一个例外就是代码贡献者重写了函数或者贡献了新的程序逻辑。

简单的代码重组和 bug 修复不应该增加新作者，这是不恰当的。

コア PEAR リポジトリにないファイルには、著作権、使用許諾契約、および作成者を示す同様のコメント ブロックが必要です。一貫性を確保するために、すべてのファイルにモードライン (vim および emacs 用) が含まれている必要があります。

---------------------------------------------- --- ----------------------------------

CVSの使用

このセクションの内容のみ.net 上の CVS を使用する cvs.php パッケージに適用されます。

各ファイルに $Id $ を含めます (2 つの $ 記号の間のキーワードにスペースを含めることはできませんが、このドキュメントも CVS によって管理されているため、CVS によって置き換えられるのを避けるためにスペースを追加する必要があります) 情報を表示するための CVS キーワードファイルの現在のステータスや最終変更時刻など。 「最終更新日:」のようなメッセージがすでに存在する場合、$Id $ タグに置き換えられます。

このセクションの残りの部分は、CVS タグとブランチに関する基本的な知識があることを前提としています。

CVS タグは、パッケージ内のファイルがリリースされる前に行われたリビジョンを識別するために使用されます。次のリストは必須および推奨される CVS タグです:

RELEASE_n_n

(必須) は、リリース バージョンをマークするために使用されます。このフラグを使用しない場合、リリースを公開するときに他の人が CVS サーバーからパッケージを取得する方法はありません。

QA_n_n

(ブランチ、オプション) リリースをリリースする前にリリース候補を提供したい場合は、ブランチを追加することをお勧めします。このブランチを使用すると、リリースを分離し、リリースをリリースする前にこれらのブランチに更新を個別に適用できます。この期間中、トランクでは通常の開発作業を続行できます。

MAINT_n_n

(ブランチ、オプション) わずかに変更されたリリースを作成する必要がある場合 (例: 1.2 の後に 1.2.1 をリリースする)。次に、目標を達成するためのブランチを作成できます。

RELEASE タグのみが必須です。便宜上、他のタグの使用をお勧めします。

以下は、「Money_Fast」パッケージ 1.2 リリース バージョンにタグを追加する方法の例です:

$ cd pear/Money_Fast
$ cvs tag RELEASE_1_2
T Fast.php
T README
T package.xml

上記の操作を完了すると、PEAR Web サイトでリリース セットを入手できます。

QA ブランチを設定する方法の例は次のとおりです:

$ cvs tag QA_2_0_BP
...
$ cvs rtag -b -r QA_2_0_BP QA_2_0
$ cvs update -r QA_2_0
$ cvs tag RELEASE_2_0RC1
.. .そして、同じブランチからの実際のリリース:
$ cvs タグ RELEASE_2_0

"QA_2_0_BP" タグは、ブランチの始まりをマークするために使用される「ブランチ ポイント」タグです。このようなマーカーでブランチの始まりを常にマークすることをお勧めします。 MAINT ブランチは、ブランチの開始点として RELEASE タグを使用できます。

---------------------------------------------- --- ----------------------------------

例のURL

すべてで使用されているURLアドレス例 これらはすべて「example.com」、「example.org」、「example.net」である必要があります。

---------------------------------------------- --- ----------------------------------

命名規則

一般的に言えば、クラス、関数および変数 コードの読み取り者がコードの動作を簡単に理解できるように、名前は常にわかりやすいものにする必要があります。

クラス

クラスにはわかりやすい名前を付ける必要があります。略語は可能な限り避けてください。クラス名は常に大文字で始める必要があります。 PEAR クラスのレベルはクラス名からも反映されます。階層内の各レベルはアンダースコアで区切られます。適切なクラス名の例は次のとおりです:

Log
Net_Finger
HTML_Upload_Error

関数とメソッド

関数とメソッドは、「studly caps」スタイルを使用して名前を付ける必要があります。他のパッケージの関数との名前の競合を避けるために、関数にはそのパッケージの名前をプレフィックスとして付ける必要があります。名前の最初の文字 (接頭辞の後) は小文字にする必要があり、新しい単語は大文字で始める必要があります。以下にいくつかの例を示します:

connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()

プライベート クラスのメンバーとプロパティ (クラス メンバーとプロパティは、同じクラスで宣言されたメンバーによってのみ使用される必要があることを意味します。ただし、PHP は使用します)必須のプライベート名前空間をサポートしていません) はアンダースコアで始める必要があります。例:

_sort()
_initTree()
$this->_status

定数

定数名は常にすべて大文字で名前を付け、単語をアンダースコアで区切る必要があります。定数名には、クラス/パッケージ名の前に大文字を付ける必要があります。例: DB:: パッケージで使用されるすべての定数は DB_ で始まります。

グローバル変数

パッケージでグローバル変数を定義する必要がある場合は、その前にアンダースコアを付け、その後にパッケージ名と別のアンダースコアを続ける必要があります。たとえば、PEAR パッケージは $_PEAR_destructor_object_list という名前のグローバル変数を使用します。

定義済みの値 true、false、null

PHP の組み込み値 true、false、null はすべて小文字で記述する必要があります。