| ユーザフォーラムで議論/質問 | マニュアル検索 | ハイライト | ハイライトオフ | ポータル | php spot |
PEAR チャネルサーバの REST インターフェイスこのセクションでは、PEAR チャネルサーバの REST インターフェイスの動作原理を説明します。 また、使用するファイルやそのフォーマットについても説明します。 ディレクトリ構造REST チャネルサーバは、特定のディレクトリ構造で構成されています。 これらのファイルの内容は静的なもので、その場所は channel.xml の baseurl タグで指定した URL からの相対パスとなります。
次の表は、これらのファイルとその簡単な説明、 そして最初に登場したバージョンをまとめたものです。
ファイルフォーマットここでは、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> タグ
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> タグ0.1.2.xml にはないタグをまとめます。
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 バージョン履歴このページでは、これまでの REST のバージョンと そのバージョンでの変更点をまとめます。 REST 1.0これは REST インターフェイスをサポートした最初のバージョンです。 REST 1.1このバージョンでは、ディレクトリ表示機能が無効になっていても チャネルを探せるようになりました。そのために、次のファイルが追加されました。 REST 1.3このバージョンから、PHP のバージョンの非互換性を リリースリストをダウンロードするだけで解決できるようになりました。 allreleases2.xml に、 個々のパッケージのリリースで必要な PHP の最低バージョンがまとめられています。 これにより、必要とする PHP の最低バージョンが変わっても パッケージ名を変更する必要はなくなりました。 使用例このセクションでは、 チャネルサーバで行う一般的な作業について説明します。 このセクションの元ネタとなっているのは、 Jean-Lou Dupont のプレゼンテーション "PEAR Channel on Google Code" です。 新しいカテゴリの追加チャネルサーバ上に新しいカテゴリを作成する際に必要な手順は 次のとおりです。
新しいパッケージの追加新しいパッケージをサーバ上で公開する際の手順は、 次のとおりです。
リリースの追加既存のパッケージの新バージョンをリリースする際の手順は次のとおりです。
Channel server softwareWhile you can use this documentation to build you own channel server, it is possibly easier for you to either get your package into PEAR itself, or setup your own channel server. The reference implementation of a PEAR channel server is the PEAR website itself, but it should not be used for your own server. If you seek for an easy-to-setup software, try Chiara_PEAR_Server which resides on its own channel http://pear.chiaraquartet.net. Another project is SimpleChannelServer, which is available as a plugin for Pyrus, or a standalone phar pearscs.phar. View the online documentation, or the source in SVN. |
各種マニュアル:
PHPマニュアル |
PEARマニュアル |
Smarty(英語)マニュアル |
PHP-GTKマニュアル |
「PEAR チャネルサーバの REST インターフェイス」をGoogle検索
|