channel.xml: チャネル定義ファイル

チャネルを定義する方法

チャネルの機能を調べるのは簡単です。 channel.xml を定義する XSD スキーマが http://pear.php.net/dtd/channel-1.0.xsd から取得可能です。 channel.xml では以下の要素を定義します。

  1. チャネル名。

  2. チャネル名に対するエイリアス (オプション)。

  3. チャネルの目的についての概要。

  4. ダウンロードやパッケージングの際にパッケージの独自検証を行う オプションのパッケージ。

  5. チャネルがサポートするプロトコルの一覧 (XML-RPC、SOAP および REST がサポートされます)。

  6. ミラーサイトとそのサイトがサポートするプロトコルの一覧。

これは、すべての要素を含んだ channel.xml の例です。

<channel version="1.0"
         xsi:schemaLocation="http://pear.php.net/channel-1.0
                             http://pear.php.net/dtd/channel-1.0.xsd">
<name>
pear.example.com</name>
<suggestedalias>
foo</suggestedalias>
<summary>
Example channel.xml</summary>
<validatepackage
version="1.3.4">Foo_Validate</validatepackage>
<servers> <primary
port="8080" ssl="yes">
<xmlrpc>
<!-- デフォルトのパスは xmlrpc.php です -->
    <function version="1.0">logintest</function>
    <function version="1.0">package.listLatestReleases</function>
    <function version="1.0">package.listAll</function>
    <function version="1.0">package.info</function>
    <function version="1.0">package.getDownloadURL</function>
    <function version="1.1">package.getDownloadURL</function>
    <function version="1.0">package.getDepDownloadURL</function>
    <function version="1.1">package.getDepDownloadURL</function>
    <function version="1.0">package.search</function>
    <function version="1.0">channel.listAll</function>
   </xmlrpc>
<rest>
<!-- デフォルトのパスはなく、必ずベース URL を指定しなければなりません -->
    <baseurl type="REST1.0">http://pear.example.com/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.com/rest/</baseurl>
   </rest>
<soap
path="soapy.php"> <!-- デフォルトのパスは soap.php です -->
    <function version="1.0">package.listAll</function>
   </soap>
  </primary>
<mirror
server="foo2.example.com/pearmirror">
   <xmlrpc path="mirrorxmlrpc.php"> <!-- デフォルトのパスは xmlrpc.php です -->
    <function version="1.0">package.listLatestReleases</function>
    <function version="1.0">package.listAll</function>
    <function version="1.0">package.info</function>
    <function version="1.0">package.getDownloadURL</function>
    <function version="1.1">package.getDownloadURL</function>
    <function version="1.0">package.getDepDownloadURL</function>
    <function version="1.1">package.getDepDownloadURL</function>
    <function version="1.0">package.search</function>
   </xmlrpc>
   <rest> <!-- デフォルトのパスはなく、必ずベース URL を指定しなければなりません -->
    <baseurl type="REST1.0">http://foo2.example.com/rest/</baseurl>
   </rest> 
  </mirror>
 </servers>
</channel>

<name>

チャネル名。これは、提供されているパッケージについての詳細情報を 調べるためにユーザが閲覧するサーバ名となります。 例えば PEAR パッケージは pear.php.net チャネルにあり、PECL パッケージは pecl.php.net チャネルにあります。過去との互換性のため、package.xml バージョン 1.0 を使用している既存パッケージは pear.php.net チャネルに 属するものとみなされます。

サーバ名をチャネル名に使用することの利点は、auto-discovery が 使用できるようになること、パッケージの配置が簡単になることです。

チャネルはドキュメントルートに存在する必要はなく、チャネルにパスを 含めることもできます。例えば以下のようなチャネル名が可能です。 foo.example.com/path/to/pear. <suggestedalias> を指定しない場合、チャネルの利用者は

     
$ pear install foo.example.com/path/to/pear/Packagename
     

とタイプしなければならないことに注意しましょう。

チャネル定義ファイル "channel.xml" がチャネルの ルートディレクトリに存在する必要があります。チャネルが "pear.example.com" の場合、channel.xml が "http://pear.example.com/channel.xml" に存在しなければ なりません。チャネルが "pear.example.com/path/to/pear" の場合、channel.xml が "http://pear.example.com/path/to/pear/channel.xml" に存在しなければなりません。

<suggestedalias>

<suggestedalias> は、パッケージをチャネルからインストールする際に 使用する、短くて使用しやすい名前を定義します。例えば、 pear.php.net チャネルの suggested alias は "pear" です。 チャネルのエイリアスは、6 文字を超えないようにしましょう。 利用者は、インストールやアップグレードの際に毎回これをタイプしなければ なりません。エイリアスが長ったらしいと、大変なことになります。

もともとこのタグは <alias> と呼ばれていましたが、利用者に より柔軟性を提供するために <suggestedalias> という名前に 変わりました。チャネルの所有者が提案 (suggest) するエイリアスが 気に入らない場合、利用者は channel-alias コマンドで簡単に 別のエイリアスを設定することができます。

<summary>

このタグでは、このチャネルで見つけられるパッケージについての情報を 簡単に説明します。これは、利用者が list-channels コマンドを 使用した際に表示されます。

<validatepackage>

多くのチャネルでは、パッケージの命名規則や バージョン番号の付与方法については PEAR がデフォルトで提供する 規則で十分でしょう。しかし、中にはこの規則が厳しすぎると感じる チャネルがあるかもしれません。また逆に緩やかすぎると感じることも あるかもしれません。<validatepackage> タグでは それをカスタマイズする機能を提供します。

省略した場合、インストーラは PEAR_Validate クラスを使用します。より緩やかなバージョン番号付与規則を提供する PEAR_Validate_PECL クラスが存在することに 注意しましょう。これは例えば、バージョン番号の規則に違反した際の PEAR の警告にかかわりたくない pecl.php.net のようなチャネルの ためのものです。

<validatepackage> には、version 属性およびテキスト要素が 必要です。テキスト要素にはパッケージ名を指定しなければなりません。 このパッケージ名は、以下のようにインストールできる必要があります。

     
$ pear install channelname.example.com/Packagename-version
     

この節のはじめに示した channel.xml の例では、

     
$ pear install pear.example.com/Foo_Validate-1.3.4
     

のようになります。さらにこのパッケージでは、パッケージ名に対応する クラスが提供されている必要があり、このクラスは PEAR の命名規約に したがったファイル名 (すべてのアンダースコア "_" を パス区切り文字 "/" に変換します。つまり、Foo_Validate は Foo/Validate.php となります) のファイルに存在する必要があります。 さらにこのクラスは PEAR_Validate を継承していなければなりません。 既存の検証機能を拡張するためには、"validate" ではじまる メソッド (validateVersion() など) を オーバーライドします。

<servers>: <primary> and <mirror>

channel.xml および PEAR インストーラでは、ミラーリングが明示的に サポートされています。利用者は、設定オプション default_channel を使用して好みのミラーを 選択することが可能で、channel.xml では使用可能なすべてのミラーを <mirror> タグで記述することができます。

プロトコルの場所を定義し、メインチャネルサーバでサポートされている プロトコルの一覧を定義するために <primary> タグを使用します。 PEAR インストーラがサーバに接続する方法を変更するために、 オプションの属性を使用することが可能です。インストーラが XML-RPC および SOAP サービスに接続する際の方法を定義するために "port" 属性を使用します。REST サービスは、常に 独立した <baseurl> タグで制御されます。

<xmlrpc>, <soap>, <rest>

channel.xml は、Web サービスのプロトコルとして XML-RPC、SOAP および REST を認識します。しかし、現時点で PEAR インストーラが サポートしているのは REST のみです。 将来は他の方式もサポートする予定です。今のところ、近いうちに SOAP がサポートされる予定はありませんが、将来それが実装された際にも channel.xml は対応可能なようになっています。

<xmlrpc> および <soap> タグの書式は同じです。それぞれの タグにはオプションの属性 "path" を含めることが可能で、 これによって PEAR に問合せ先 URL を教えます。デフォルトのパスは プロトコル.php、つまり xmlrpc.php あるいは soap.php となります。 言い換えれば、上の例の channel.xml で定義されたチャネル pear.example.com の XML-RPC 関数にアクセスするためには、インストーラは https://pear.example.com:8080/xmlrpc.php (XML-RPC 関数の場合)、あるいは https://pear.example.com:8080/soapy.php (SOAP 関数の場合) に問い合わせます。

<rest> タグは REST の設計思想を反映しています。各リソースは <baseurl> タグ内のベース URL で定義され、インストーラは XML-RPC あるいは SOAP が提供するのと同じ情報を ハイパーリンクを通じて取得します。 必須属性 "type" により、ベース URL から提供される PEAR インストーラ REST インターフェイスのバージョンをインストーラに教えます。

<function>

<function> タグは、きわめてシンプルです。必須属性 version によって API を、そしてテキスト要素によって関数の名前を インストーラに教えます。以下のように、バージョンの違う複数の関数を 共存させることが可能であることに注意しましょう。

<function version="1.0">package.getDownloadURL</function>
<function version="1.1">package.getDownloadURL</function>

新しい API が過去との互換性を保っている場合、使用可能なすべての バージョンを定義しておきましょう。これにより、旧バージョンの インストーラもその API を使用できるようになります。

なぜ wsdl のような標準を使用しないのですか?

皆さんの中には「Web サービスを探すために、なぜまた新たな標準を 作ったりするのか?」と思うかたもおられるでしょう。答えは単純です。 channel.xml は、java における WSDL の役割を担うものでは ありませんし、また XML-RPC に取って代わるものでもありません。 channel.xml は、これらの技術の上位階層に位置するものです。 大事なのはサポートされているリモートプロトコルの一覧を すばやく取得することであり、それが何を行うのかを説明することでは ありません。

PEAR インストーラは、一般的なパラメータや返り値のリストが必要ないほど 専門化されており、xml-rpm 関数 package.info バージョン 1.0 が 何を必要として何を返すのかを正確に知っています。 それ以外の情報は、単に帯域およびディスク領域を浪費するだけになります。

channel.xml, REST, XML-RPC (Previous) PEAR チャネルサーバの REST インターフェイス (Next)
Last updated: Tue, 29 Jul 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:

There are no user contributed notes for this page.