規則

この標準規約で使用する規則について説明します。

名前空間プレフィックス

すべてのクラスや関数は、少なくとも 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'
);
}
?>

要件

このルールはオプションで、推奨するコーディング手法です。

導入 (Previous) PEAR2 Policies (Next)
Last updated: Thu, 18 Sep 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

Note by: spamfriends at googlemail dot com
Well, the PEAR2 "root" namespace seems to be superfluous. Especially for large packages that contain more than one level of nested directories/namespaces.
Beside the overhead one has to type, this also looks very awkward. And in previous versions of PHP and PEAR coding standards no-one was forced to use a "PEAR_" prefix either...

I understand that this might be necessary in order to use some universal PEAR2\Autoloader that does not affect other namespaces, but a (maybe static) method like PEAR2\Autoloader::registerNamespace($prefix) should also do the trick. Or simply leave it to the package maintainer to implement autoloading in "extern" namespaces.

Last but not least; neither CPAN, PyPI nor any of the other popular networks have ever introduced such a rule. I'm pretty sure they know why...