PEAR マニュアル
前のページ	第 33 章 PEAR チャネルサーバの REST インターフェイス	次のページ

ファイルフォーマット

ここでは、REST インターフェイスで使用するファイルフォーマットについて詳細に説明します。

一般に、ファイルのサイズはできるだけ小さくすべきです。そうすれば、ファイルを取得する際に余計な帯域を使わなくてすみます。ということもあり、すべての xml ファイル (元の package.xml は除く) で使用するタグの名前は 1 文字か 2 文字のものにしています。 pear list-all のようなコマンドを実行すると、大量のファイルをダウンロードすることになるので、些細なことですがこれはかなりの帯域の節約になります。

channel.xml

チャネルについての情報

これは、そのチャネルで最も重要なファイルです。このファイルがなければ何も動作しません。チャネルを発見するときに、このファイルを取得します。このファイルでは REST ディレクトリとそのミラーの場所を定義します。

チャネル名 <name> は完全修飾形式のドメイン名で、たとえば channel.xml ファイルを更新する際の URL の一部として使用します。

PEAR では、チャネル名の短縮版となるエイリアスを提供しています。これは日常の作業で用いられるものです。 <suggestedalias> に、短くて書きやすい単語を指定します。たとえばエイリアスが nice であったとすると、
pear install pear.mynicelittlespaceon.example.org/package
とする代わりに
pear install nice/package
とタイプするだけでよくなります。

場所

/channel.xml

そのドメインのルートディレクトリになければなりません。その他のファイルはどこか特定のディレクトリ配下に置くこともできますが、 channel.xml だけは / になければならないのです。

例

<?xml version="1.0" encoding="utf-8"?>
<channel version="1.0"
         xmlns="http://pear.php.net/channel-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pear.php.net/channel-1.0
                             http://pear.php.net/dtd/channel-1.0.xsd"
>
 <name>pear.example.org</name><!-- URL, used to update channel.xml and such -->
 <suggestedalias>example</suggestedalias>
 <summary>Simple demo channel server</summary>
 <servers>
  <primary>
   <!-- you can ignore xmlrpc, it's deprecated anyway -->
   <xmlrpc>
    <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>
    <baseurl type="REST1.0">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://pear.example.org/rest/</baseurl>
   </rest>
  </primary>

  <mirror host="us.pear.example.org">
   <rest>
    <baseurl type="REST1.0">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.1">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.2">http://us.pear.example.org/rest/</baseurl>
    <baseurl type="REST1.3">http://us.pear.example.org/rest/</baseurl>
   </rest>
  </mirror>

  <mirror host="de.pear.example.org" ssl="yes" port="3452">
   <rest>
    <baseurl type="REST1.0">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.1">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.2">https://de.pear.example.org:3452/rest/</baseurl>
    <baseurl type="REST1.3">https://de.pear.example.org:3452/rest/</baseurl>
   </rest>
  </mirror>

 </servers>
</channel>

categories.xml

全カテゴリの一覧

サーバ上の全カテゴリの名前とリンクを記述します。リンクは URL エンコードします。

位置

c/categories.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allcategories"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allcategories
                       http://pear.php.net/dtd/rest.allcategories.xsd"
>
 <ch>pear.example.org</ch>
 <c xlink:href="/rest/c/Tools/info.xml">Tools</c>
 <c xlink:href="/rest/c/Garbage%2Band%2BStuff/info.xml">Garbage and Stuff</c>
</a>

info.xml (カテゴリ)

カテゴリについての情報

ここで、カテゴリの詳細を説明します。このファイルにはカテゴリ名 (<n>)、チャネルサーバ (<c>)、エイリアス (<a>) そしてカテゴリについての長い説明 (<d>) を記述します。

位置

c/${categoryname}/info.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<c xmlns="http://pear.php.net/dtd/rest.category"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.category
                       http://pear.php.net/dtd/rest.category.xsd"
>
 <n>Tools</n>
 <c>pear.example.org</c>
 <a>Tools and Utilities</a>
 <d>This category holds all sorts of packages that might help you when
  trying to dominate the world.</d>
</c>

packages.xml (カテゴリ)

カテゴリ内の全パッケージの一覧

このファイルには、そのカテゴリ内の各パッケージの名前とリンクの一覧が含まれます。

位置

c/${categoryname}/packages.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<l xmlns="http://pear.php.net/dtd/rest.categorypackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackages
                       http://pear.php.net/dtd/rest.categorypackages.xsd"
>
 <p xlink:href="/rest/p/earth">Earth</p>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
</l>

packagesinfo.xml

すべてのパッケージについての情報

packagesinfo.xml は、カテゴリ内のパッケージについての情報を集めたものです。パッケージの info.xml の内容は allreleases.xml からのリリース情報、そして各バージョンの依存性情報などが含まれます。

すべてのパッケージ情報は、それぞれ <pi> タグで囲みます。

位置

c/${categoryname}/packagesinfo.xml

使用法

list-all コマンドで表示される "サマリ" 情報を記述します。

例

<?xml version="1.0" encoding="utf-8" ?>
<f xmlns="http://pear.php.net/dtd/rest.categorypackageinfo"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.categorypackageinfo
                       http://pear.php.net/dtd/rest.categorypackageinfo.xsd"
>
<pi>
<?xml version="1.0" encoding="UTF-8" ?>
<p xmlns="http://pear.php.net/dtd/rest.package"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.package
                       http://pear.php.net/dtd/rest.package.xsd"
>
 <n>WorldDominator</n>
 <c>pear.example.org</c>
 <!-- Full contents of p/${packagename}/info.xml follow -->
</p>
<a>
 <r><v>1.1.2</v><s>stable</s></r>
 <r><v>0.1.2</v><s>beta</s></r>
 <r><v>0.0.1</v><s>devel</s></r>
</a>
<deps>
 <v>0.1.2</v>
 <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
</deps>
<deps>
 <v>0.0.1</v>
 <d><!-- serialized dependency information like deps.0.1.2.txt --></d>
</deps>
</pi>
</f>

allmaintainers.xml

全メンテナの一覧

サーバ上のパッケージの全開発者の名前とリンクを記述します。

FIXME: full names or just nicks? FIXME: lowercased nicks?

位置

m/allmaintainers.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.allmaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allmaintainers
                       http://pear.php.net/dtd/rest.allmaintainers.xsd"
>
 <h xlink:href="/rest/m/pinky">pinky</h>
 <h xlink:href="/rest/m/thebrain">the brain</h>
</m>

info.xml (メンテナ)

メンテナの情報

メンテナの情報、たとえばハンドル (ニックネーム、<h>)、フルネーム (<n>) ホームページの URL (<u>) などを記述します。

位置

m/${maintainernick}/info.xml

FIXME: lowercasednick?

例

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.maintainer"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.maintainer
                       http://pear.php.net/dtd/rest.maintainer.xsd"
>
 <h>thebrain</h>
 <n>The Brain</n>
 <u>http://pinkyandthebrain.example.org</u>
</m>

packages.xml (p)

全パッケージの一覧

このパッケージは、チャネル内のすべてのパッケージの一覧とチャネルサーバ名そのものを記述します。

パッケージ名に空白文字を含めることはできません。空白文字を含めた場合、インストーラの挙動は未定義となります。

位置

p/packages.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allpackages"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allpackages
                       http://pear.php.net/dtd/rest.allpackages.xsd"
>
 <c>pear.example.org</c>
 <p>Earth</p>
 <p>WorldDominator</p>
</a>

info.xml (パッケージ)

パッケージについての情報

このファイルには、そのパッケージのバージョンに依存しない一般的な情報を記述します。たとえばライセンス、カテゴリ、サマリ、説明、リリースディレクトリへのリンクなどです。

位置

r/${packagename}/info.xml

使用法

remote-info は、このファイルを取得して情報を表示します。

例

<?xml version="1.0" encoding="utf-8" ?>
<p xmlns="http://pear.php.net/dtd/rest.package"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.package
                       http://pear.php.net/dtd/rest.package.xsd"
>
 <n>WorldDomination</n>
 <c>pear.example.org</c>
 <ca xlink:href="/rest/c/Tools">Tools</ca>
 <l>Dictatoric License</l>
 <s>Tool to dominate the world</s>
 <d>
  Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42
 </d>
 <r xlink:href="/rest/r/worlddomination"/>
</p>

maintainers.xml

パッケージのすべての開発者の一覧

アクティブか否かにかかわらず、すべての開発者をこのファイルに記述します。

各開発者のハンドル (<h>) および活動状況 (<a>、0 が非アクティブで 1 がアクティブ) を記述します。

位置

r/${packagename}/maintainers.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
 </m>
</m>

maintainers2.xml

パッケージの開発者の一覧

maintainers.xml と同じですが、さらに開発者のロールも含まれています。

ロール名として使用できるのは lead、developer、 contributor および helper です。

位置

r/${packagename}/maintainers2.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<m xmlns="http://pear.php.net/dtd/rest.packagemaintainers"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.packagemaintainers
                       http://pear.php.net/dtd/rest.packagemaintainers.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <m>
  <h>pinky</h>
  <a>1</a>
  <r>developer</r>
 </m>
 <m>
  <h>thebrain</h>
  <a>1</a>
  <r>lead</r>
 </m>
 <m>
  <h>deadcow</h>
  <a>0</a>
  <r>helper</r>
 </m>
</m>

allreleases.xml

全パッケージのバージョンの一覧

このファイルには全パッケージのバージョンと安定性が記述されています。

複数のリリースがある場合、このファイルでは最新のバージョンが先頭にくるようにします。

位置

r/${packagename}/allreleases.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases
                       http://pear.php.net/dtd/rest.allreleases.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s></r>
 <r><v>0.0.2</v><s>alpha</s></r>
</a>

allreleases2.xml

全パッケージのバージョンと PHP のバージョンの一覧

allreleases.xml と同じですが、さらに、必要となる PHP の最小バージョンについての情報が追加されています。

位置

r/${packagename}/allreleases2.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<a xmlns="http://pear.php.net/dtd/rest.allreleases2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.allreleases2
                       http://pear.php.net/dtd/rest.allreleases2.xsd"
>
 <p>WorldDominator</p>
 <c>pear.example.org</c>
 <r><v>0.8.1</v><s>beta</s><m>4.4.2</m></r>
 <r><v>0.0.2</v><s>alpha</s><m>5.2.3</m></r>
</a>

latest.txt

最新のパッケージのバージョン

このファイルの唯一の中身は、最新版のバージョン番号をプレーンテキストで書いたものです。安定性は関係なしに、もっとも新しいバージョン番号をここに書きます。

位置

r/${packagename}/latest.txt

最新版がリリースされていない場合は、このファイルも存在しません。

例

このパッケージには安定版のバージョン 1.0.0 のほかに 0.9.8 と 1.0.9 のふたつのベータ版、そして開発版の 1.0.1 が存在すると仮定しましょう。最新のバージョン番号はこの場合 1.0.9 なので、これを latest.txt に記述します。

1.0.9

stable.txt

最新の安定版のバージョン

このファイルの唯一の中身は、最新の安定版のバージョン番号をプレーンテキストで書いたものです。

位置

r/${packagename}/stable.txt

安定版が存在しない場合は、このファイルも存在しません。

例

0.1.2

beta.txt

最新のベータ版のバージョン

このファイルの唯一の中身は、最新のベータ版のバージョン番号をプレーンテキストで書いたものです。

位置

r/${packagename}/beta.txt

ベータ版が存在しない場合は、このファイルも存在しません。

例

0.1.2

alpha.txt

最新のアルファ版のバージョン

このファイルの唯一の中身は、最新のアルファ版のバージョン番号をプレーンテキストで書いたものです。

位置

r/${packagename}/alpha.txt

アルファ版が存在しない場合は、このファイルも存在しません。

例

0.1.2

devel.txt

最新の開発版のバージョン

このファイルの唯一の中身は、最新の開発版のバージョン番号をプレーンテキストで書いたものです。

位置

r/${packagename}/devel.txt

開発版が存在しない場合は、このファイルも存在しません。

例

0.1.2

0.1.2.xml (リリース)

そのリリースに関する短い xml ファイル

このファイルは、完全版の package.xml から必要最小限の情報に絞り込んでサイズを最適化したファイルです。

package.xml と同様タグの順序が重要であり、入れ替えてはいけません。

位置

r/${packagename}/0.1.2.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release
                       http://pear.php.net/dtd/rest.release.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

タグ名	説明
`<p>`	パッケージのディレクトリへの絶対パスを含めたパッケージ名
`<c>`	チャネルサーバ名
`<v>`	リリースバージョン
`<st>`	安定性 (`stable`、`beta` など)
`<l>`	ライセンス名
`<m>`	リリース担当開発者のハンドル/ニックネーム
`<s>`	サマリ
`<d>`	複数行の説明
`<da>`	リリース日時
`<n>`	リリースノート
`<f>`	バイト単位の tgz のサイズ
`<g>`	リリースアーカイブへの完全な URL
`<x>`	そのバージョンの `package.xml` ファイルへのリンク

v2.0.1.2.xml

そのリリースに関する短い xml ファイルのバージョン 2

0.1.2.xml と同じですが、追加の API と最小 PHP バージョンが増えています。

位置

r/${packagename}/v2.0.1.2.xml

例

<?xml version="1.0" encoding="utf-8" ?>
<r xmlns="http://pear.php.net/dtd/rest.release2"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xsi:schemaLocation="http://pear.php.net/dtd/rest.release2
                       http://pear.php.net/dtd/rest.release2.xsd"
>
 <p xlink:href="/rest/p/worlddominator">WorldDominator</p>
 <c>pear.example.org</c>
 <v>0.1.2</v>
 <a>0.1.2</a>
 <mp>5.2.3</mp>
 <st>beta</st>
 <l>Dictatoric License</l>
 <m>thebrain</m>
 <s>Tool to dominate the world</s>
 <d>Helps you dominating the world by fulfilling various tasks:
  - Feed the cats
  - Lock the doors after 23:42</d>
 <da>2007-12-24 23:42:00</da>
 <n>* Fix atomic X-mas bug [thebrain]</n>
 <f>19588</f>
 <g>http://pear.example/get/WorldDominator-0.1.2</g>
 <x xlink:href="package.0.1.2.xml"/>
</r>

タグ名	説明
`<a>`	API バージョン
`<mp>`	最小の PHP バージョン

package.0.1.2.xml

完全な package.xml

このリリースの完全な package.xml です。バージョン 1 あるいはバージョン 2 の package.xml 形式となります。そのパッケージに両方が含まれている場合はバージョン 2 のほうを使用します。

位置

r/${packagename}/package.0.1.2.xml

deps.0.1.2.txt

シリアライズした依存性情報

このファイルには、依存性情報の配列を PHP の serialize() 関数でシリアライズしたものが保存されます。

位置

r/${packagename}/deps.0.1.2.txt

依存性配列 (シリアライズしていない xml 形式) の例

array(2) {
  ["required"]=>
  array(2) {
    ["php"]=>
    array(1) {
      ["min"]=>
      string(5) "5.2.3"
    }
    ["pearinstaller"]=>
    array(1) {
      ["min"]=>
      string(7) "1.7.1"
    }
  }
  ["optional"]=>
  array(1) {
    ["package"]=>
    array(2) {
      ["name"]=>
      string(4) "Toolbox"
      ["channel"]=>
      string(12) "pear.example.org"
      ["min"] =>
      string(7) "1.3.0"
    }
  }
}

<dependencies>
  <required>
   <php>
    <min>5.2.3</min>
   </php>
   <pearinstaller>
    <min>1.7.1</min>
   </pearinstaller>
  </required>
  <optional>
   <package>
    <name>Toolbox</name>
    <channel>pear.example.org</channel>
    <min>1.3.0</min>
   </package>
  </optional>
 </dependencies>

前のページ	ホーム	次のページ
ディレクトリ構造	上に戻る	REST バージョン履歴