規則
この標準規約で使用する規則について説明します。
名前空間プレフィックス
すべてのクラスや関数は、少なくとも PEAR2 名前空間の配下にある必要があります。 たとえば次のようになります。
<?php
namespace PEAR2;
class MyClass {}
?>
クラスの名前空間をもっと長いものにすることもできます。 たとえば、HTTP_Request クラスを作成する代わりに次のような構文を使用します。
<?php
namespace PEAR2::HTTP;
class Request {}
?>
このようにすることで、名前空間があればクラス名のアンダースコアは不要となります。 PEAR2_HTTP_Request のようなクラス名ではなく PEAR2::HTTP::Request となるのです。 しかし、パッケージ名ではアンダースコアを使います。 この場合のパッケージ名は PEAR2_HTTP_Request となります。
要件
このルールには例外はありません。
include/require/require_once/include_once を使用してはいけない
include/require/require_once/include_once を、 クラスファイルを読み込むために使用してはいけません。 クラスファイルを読み込むには、__autoload() を使用します。あるいは上級者向けには独自の手法を用意します。 その代わりに、クラスの使用法は簡単にしなければなりません。 そのクラスの場所がわかるようなコメントをつけてインポートを行い、 内部の依存関係をすべてドキュメント化します (あとで説明します)。
<?php
require_once 'PEAR2/OtherPackage.php';
$class = new PEAR2::OtherPackage;
?>
このような方法ではなく、次のようにシンプルに使えなければなりません。
<?php
$class = new PEAR2::OtherPackage;
?>
こうすることで、どんな場合でも (ディスク上にディレクトリ構造ができている場合でも単一の大きなファイルの場合でも、 あるいは phar アーカイブにまとめられている場合でも) 変更なしにパッケージを動作させられるようになり、 より柔軟なものとなります。
要件
このルールには例外はありません。
ディレクトリ構造
PEAR2 Subversion ディレクトリ内のディレクトリ構造にしたがってください。
PEAR2/Package_Name/
src/ <-- role="php" のファイルすべて
data/ <-- role="data" のファイルすべて
tests/ <-- role="tests" のファイルすべて
doc/ <-- role="doc" のファイルすべて
www/ <-- role="www" のファイルすべて
examples/ <-- role="doc" のサンプルファイル
(パッケージの使用法を示す、php の実行可能ファイル)
すべての package.xml ファイルでは、src/ ディレクトリの baseinstalldir に "/" を指定しなければなりません。
<contents> <dir name="/"> <dir name="src" baseinstalldir="/"> ... </contents>
要件
このルールに対して例外を認めるには PEAR Group の許可が必要です。
クラス名とファイル名の対応
すべての公開クラスは、そのクラス名のアンダースコア (_) あるいは名前空間セパレータ (::) の部分をディレクトリ区切り文字に置き換えた場所になければなりません。 つまり、PEAR2_PackageName_Base クラスや PEAR2::PackageName::Base クラスは PEAR2/PackageName/Base.php というファイルに書くことになります (これは、autoload を機能させるために必須です)。
要件
このルールに対して例外を認めるには、公開投票を行ったうえでの PEAR Group の明示的な許可が必要です。
基底例外クラス
PEAR2::Exception が、すべての例外クラスの基底クラスとなります。 個々のパッケージでは、packagename_Exception という名前の基底クラスを定義しなければなりません。 たとえば PEAR2::PackageName クラスでは、 次のような例外クラスを PEAR2/PackageName/Exception.php で定義します。
<?php
namespace PEAR2::PackageName;
class Exception extends PEAR2::Exception {}
?>
PEAR2::Exception 自身もパッケージとなります。
要件
このルールには例外はありません。
データファイル
package.xml の replacement タスクを使用して php ファイルやデータファイル、 www ファイルのパスを取得してはいけません。 しかし、doc ファイルや test ファイルについては置換を使用してもかまいません。
パッケージのインストール先は php_dir/src であり、 データファイルの場所は、常に php_dir/data/channel/PackageName/ となります。 PEAR2/PackageName/Subfile.php の中からデータファイルを取得するには、このようなコードを使用します。
<?php
...
// info.txt からデータを取得します
$info = file_get_contents(dirname(__FILE__) .
'../../../data/pear2.php.net/PEAR2_PackageName/info.txt');
?>
要件
このルールには例外はありません。
他のクラスの読み込み
オプションのコンポーネントを読み込むメソッド (ファクトリメソッドやドライバの読み込みなど) の内部で class_exists($classname, true) を使用し、致命的なエラー "class not found" となることを避けます。 たとえばドライバの読み込みに失敗した場合は、 単なる致命的なエラーにしてしまうのではなく わかりやすいメッセージをつけた例外を発生させて終了することをお勧めします。
<?php
if (!class_exists("PEAR2_PackageName_Driver_$class", true)) {
throw new PEAR2::PackageName::Exception('Unknown driver ' .
$class . ', be sure the driver exists and is loaded
prior to use');
}
?>
要件
このルールはオプションで、推奨するコーディング手法です。
忘却曲線を使ってこの知識を確実に記憶に残す
