開発者向けの FAQ

PEAR に協力したいのですが、どうすれば良いですか? また、CVS へのアクセス方法は?

こちら を参照してください。

拡張モジュールを C 言語で書いたのですが、 それを PEAR に採用してもらうにはどうすれば良いですか?

PECL プロジェクト (PEAR から分離しました)が PHP 用の C 拡張モジュールを公表する場所になります。

なぜ PEAR は pear/ と pear-core/ に分かれているのですか?

PEAR の初期の要素は pear-core (元 php-src/pear) ディレクトリに保存され、 PHP リリースにバンドルされていました。

しかし PEAR は今後、PHP リリースにバンドルできる大きさを超えることが見込まれ、 上記の方法ではうまく行きません。そこで、新しい要素はすべて pear という トップレベルディレクトリにコミットすることにしました。 今のところ php-src/pear にある要素も、まもなくこの新しい トップレベルディレクトリに移されます。 PEAR パッケージマネージャだけが、PHP の新しいリリースに バンドルされるようになります。

どうして pear/ と pear-core/ でディレクトリ構造が違うの?

pear-core/ のディレクトリ構造は、 インストールツリー (デフォルトでは/usr/local/lib/php) そのままのシンプルな構造になっています。 一方、pear/ の構造は、 各ファイルがどのパッケージに属するかを示しています。 それぞれのパッケージごとに作られたディレクトリ中で、 個々のファイルの位置は、インストール後の位置とは完全に独立しています。 インストール後の位置は、パッケージ記述ファイルにより指定されます。

どうしてフラットなディレクトリ構造をとっているの?

CVS においては、PEAR のコードはパッケージごとにまとめられています。 インストールされた後の最終的な階層構造とは異なっています。 たとえば、XML_RPC クラスを使うときは、"XML/RPC.php" を読み込みます。 単純に想像すると、そのファイルは CVS で pear/XML/RPC.php にありそうですが、そうではありません。 XML_RPC は、独立のパッケージなので CVS では専用のディレクトリがあります。 RPC.php は pear/XML_RPC/RPC.php にあるのです。 パッケージ記述ファイル (package.xml) を使って、ファイルが最終的にどこに インストールされるかが指定されます。

CVS が、なぜこのように構成されるかと言うと、 パッケージ管理がとても簡単になるからです。

実験的または不安定なものをコミットしてよいですか?

はい。ただし、ドキュメントに プロジェクトの実験性・不安性についてのステータスを 確実に書き加えてください。書き加える最良の場所は、 package.xml の <status> タグです。 このタグには、次の値のいずれかを指定します。

alpha
開発の初期段階であって、(APIや動作など) すべてが無断で変わることがあり、バグも多くあることが予想される。
beta
API は、ほとんど変わらず、使用可能なソフトウェアだが、 バグも多くあることが予想される。
devel
テストとフィードバックのために早期に公開する、 開発者のためのリリース。 コード品質は pre-alpha から stable まで様々。
stable
API が固定しており、テストは実施済みで、 ドキュメントも書かれているもの。 実運用環境に推奨のリリース。
snapshot
ある時点の CVS スナップショット。

パッケージに、そのサンプルやテスト用のファイルは必要ですか? 必要なら、どこに保存すればよいですか?

サンプルを添付するのは良い考えです。クラスの API が複雑な場合には特にそうです。 しかし、サンプルはドキュメントの一部でしかありません。 ドキュメントの代わりにサンプルだけを作るのはやめましょう。 ドキュメントとサンプルは共に 'docs' サブディレクトリに置いてください。

クラスが、コンパイルが必要であったり、 特別な拡張モジュールやプログラムを必要とする場合、さらに (テンプレートや画像などの)追加ファイルが正しくインストールされている 必要がある場合は、テストスクリプトの作成を推奨します。 テストスクリプトは、'tests' サブディレクトリに置いてください。

似たような機能を持つ別のパッケージやクラスは認められますか?

パッケージの機能が互いに競合すること自体には問題はありません。 しかし、10 のテンプレートクラス、7 つものメール処理クラス、 3 つのデータベースレイヤが、関数名が異なるだけで同じ動作をするといった 「汚染」は避けたいと思っています。

まず真実に目を向けてください。 なぜ私は新しいパッケージをコミットしたいのか、と。 "PEAR で有名になりたい" とか、"既存クラスのAPIを理解していないから" というのは、 非常に悪い答えです。

新しいクラスを作る良い理由としては、 既存の実装に特定の機能や動作・速度が欠けているということでしょう。 しかしこの場合も、拡張が可能なら、既存のクラスをなんとかしてみるべきです。 そうできなかった場合だけ、新しいクラスをコミットするための正当な理由があることとなります。 ここで、"そうできなかった" とは、 既存のクラスを基礎から変更せずには必要な機能を付加できない、 ということを意味しています。

新しいクラスを書く際は、 既存のクラスとの API 互換性を維持するよう可能な限り努めてください。 互換性の維持ができない場合は、 互換性を維持するラッパクラスを作成してください。 ラッパクラスは互換性を維持し、移行をより簡単にするためだけのものですから 作動時間・メモリを多く必要としても気にしないでください。

また、競合するクラスをコミットする際には、 PEAR 開発者メーリングリスト で告知しなければなりません。

require したパッケージが別のパッケージを読み込んでいます。 後者のパッケージが直接必要となった場合は、再び読み込むべきですか?

はい。他のパッケージによって、読み込みが行われる場合でも、 必要なパッケージはすべて読み込むべきです。 このとき、require_once() または include_once() を使う必要があります。

PEAR/PECL で使用できるライセンスは?

現在のところ PEAR では次のライセンスが使用できます。

他のライセンスは、ケースバイケースベースでこのリストに追加されます。 追加のためには、PEAR developers mailing list に連絡をしてください。

これらのライセンスは、クローズドソースやオープンソースのアプリケーションと 組み合わせて使用することが許可されています。 また、商用アプリケーションとも組み合わせることができます。 唯一の制約は、原作者のクレジットをソースの中に残しておく必要があるということです。 LGPL については、これに加えて 「ソースコードに改変を加えたものを再配布する際には、 改変部分も LGPL ライセンスにしなければならない」 という制約があります。

PHP ライセンスの PEAR パッケージを GPL のコードで使用することについて心配される人もいるようです。 この件については、PHP の作者である Rasmus Lerdorf が このような声明 を出しています。

It all comes down to semantics of what linking means. The PHP license is pretty much identical to the Apache license and you could indeed make a case for not allowing any GPL'ed software to be "linked to" from Apache either.

See http://www.apache.org/licenses/LICENSE-1.1.

The PHP license was chosen to match the Apache license because Apache and PHP are tied so closely to each other.

This hair splitting over linking, derivation and aggregation has been going on since the beginning of time. My stance is that you can indeed ship PHP licensed PEAR components on the same cd or in the same tarball as GPL'ed code because I see it as an aggregate work. This changes if you take PEAR code, modify it and copy-paste it directly into your own work. Then it moves from aggregate to derived. But the intent of the PEAR components is to be used in aggregate form. The PHP license allows you to use it in derived form as well, of course, but then you should be choosing a license other than the GPL for the derived work.

The FSF has a FAQ on aggregation here: http://www.fsf.org/licensing/licenses/gpl-faq.html#MereAggregation

That text is heavily biased towards compiled software and they talk about executables and memory spaces which don't really apply in this case. If you don't consider using a PEAR component as aggregation then it logically follows that you also cannot have Apache call your code so you will have to stipulate that nobody can use your code from Apache. I think this is an extreme interpretation that pretty much nobody out there shares.

In short, I don't see an issue here. Move along.

PHP にリンクされる PECL 拡張モジュールについては、PHP ライセンスと 矛盾の無いライセンスでなければなりません。つまり、PECL 拡張を GPL とすると GPL に違反してしまうということです。さらに、GPL なライブラリとリンクする 拡張モジュールを書いた場合にも、GPL に違反するということに注意してください。 GPL なライブラリとリンクする必要がある場合には、 矛盾のないライセンスを使用できるよう、 ライブラリの著者に許可を得てください。

PEAR/PECL パッケージのライセンスは、すべてのソースファイルの先頭に記述されています。 また、パッケージ記述ファイル (package.xml) の <license> タグ内、そしてパッケージのホームページにも記述されています。

PEAR 標準コーディング規約で、なぜインデントはスペースのみなのですか?

コードにタブを使用せずスペースを用いることは、すべてのエディタや ビューワで共通した表示が得られる唯一の方法です。 タブを 4 つのスペースとして扱うエディタが通常ですが、 8 つのスペースとして扱うターミナルやユーティリィティも多くあります。 例を示します。

printf("%s",
       $arg);

この例では、7 つのスペースが "$arg" の前にあります。 もしこのコードが 4 スペース-タブのエディタで書かれるとすれば、 1 つのタブおよび 3 つのスペースとして記述されるでしょう。 もし他の開発者が 8 スペース-タブのエディタで 同じファイルを編集すると,次のように見えるでしょう。

printf("%s",
           $arg);

おなじように、8 スペース-タブで書かれた次のコードを考えてみます。

    if ($foo &&
        $bar) {
    }

4 スペース-タブのエディタでは,次のように見えます。

    if ($foo &&
    $bar) {
    }

PEAR のようなコミュニティでは、 さまざまなシステムやエディタが使用されるので、 タブを使うと上記のような問題が起きるのです。 他人にはうまく表示されないとすれば、 結局、スペースを使って体裁を整えるしかありません。 スペースを使うことだけが、誰が見ても同じように見えるようにする 唯一の方法なのです。

Jamie Zawinski が この問題について も記しています。

また、コードを適切なスタイルに変換する助けとなるツールに、 Astyle があります。

ユーザ向け FAQ (Previous) ドキュメント作成や翻訳に関する FAQ (Next)
Last updated: Wed, 16 Apr 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: doconnor
Astyle is alright, but the latest thing we use is PHP_CodeSniffer.