[prev in list] [next in list] [prev in thread] [next in thread]
List: pear-doc
Subject: [PEAR-DOC] cvs: peardoc /ja/guide/migrating customroles.xml customtasks.xml postinstall.xml
From: "TAKAGI Masahiro" <takagi () php ! net>
Date: 2007-04-22 1:38:48
Message-ID: cvstakagi1177205928 () cvsserver
[Download RAW message or body]
takagi Sun Apr 22 01:38:48 2007 UTC
Added files:
/peardoc/ja/guide/migrating postinstall.xml customtasks.xml
customroles.xml
Log:
initial translation.
["takagi-20070422013848.txt" (text/plain)]
http://cvs.php.net/viewvc.cgi/peardoc/ja/guide/migrating/postinstall.xml?view=markup&rev=1.1
Index: peardoc/ja/guide/migrating/postinstall.xml
+++ peardoc/ja/guide/migrating/postinstall.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.3 Maintainer: takagi Status: ready -->
<chapter id="guide.migrating.postinstall">
<chapterinfo>
<author>
<firstname>Gregory</firstname>
<surname>Beaver</surname>
</author>
<date>$Date: 2007/04/22 01:38:48 $</date>
</chapterinfo>
<title>インストール後に実行するスクリプト</title>
<warning>
<title>不完全なドキュメント</title>
<para>このドキュメントは、ま 書きかけです。</para>
</warning>
<simpara>
インストール後に実行するスクリプトを package.xml \
で定義するための XML の書式は、<link \
linkend="guide.developers.package2.tasks.postinstallscript"> ここ</link> \
で説明されています。このドキュメントでは、 \
インストール後に実行する PHP スクリプト自身にしての必 要 \
を説明します。 </simpara>
<sect1 id="guide.migrating.postinstall.naming">
<title>インストール後に実行する PHP \
スクリプトファイルの命名規約</title> \
<titleabbrev>スクリプトの名前</titleabbrev> <para>
インストール後に実行するスクリプトには、何でもお望みの名前をつけることが可能です。
しかし、そのファイル内で定義するクラスの名前がファイル名と一致しなければなりません。
その際、パスの区切り文字はアンダースコアに変換します。
つまり、
</para>
<para>
<filename>Path/To/Script.php</filename>
</para>
<para>
のようなスクリプトには、クラス \
<classname>Path_To_Script</classname> \
が存在する必要があるということです。 \
ご利用のオペレーティングシステ \
によっては大文字小文字の扱いが異なることもあるので、 \
ファイル名には常に小文字を使用することを推奨します。 \
</para> </sect1>
<sect1 id="guide.migrating.postinstall.structure">
<title>スクリプトの構 </title>
<titleabbrev>スクリプトの構 </titleabbrev>
<para>
インストール後に実行するスクリプトのクラスには、二つのメソッドが必 \
となります。 ひとつは \
<function>init</function>、そしてもうひとつは <function>run</function> \
です。<function>init</function> \
メソッドは、すべてのスクリプトで同時に実行されます。 \
<function>run</function> \
メソッドは各パラメータグループの最後にコールされ、 \
問い合わせに対するユーザの応答を処理します。 </para>
<sect2 id="guide.migrating.postinstall.structure.init">
<title><function>init</function> メソッド</title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>init</function></funcdef>
<paramdef>PEAR_Config <parameter>$config</parameter></paramdef>
<paramdef>PEAR_PackageFile_v2 <parameter>$self</parameter></paramdef>
<paramdef>string|null <parameter>$lastInstalledVersion</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
<variablelist>
<varlistentry>
<term>
<link linkend="core.ppm.pear-config">PEAR_Config</link> \
<parameter>$xml</parameter> </term>
<listitem>
<para>
インストールに使用する現在の設定。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
PEAR_PackageFile_v2 <parameter>$self</parameter>
</term>
<listitem>
<para>
package.xml の内容をこのオブジェクトで抽象化したもの。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
&type.string;|&null; <parameter>$lastInstalledVersion</parameter>
</term>
<listitem>
<para>
このパッケージの、最後にインストールされたバージョン。
これは非常に重要なパラメータで、
新規インストールなのか更新インストールなのかを確認する唯一の手がかりとなります。
このパラメータを使用すると、更新時の処理が必要かどうかを判断できます。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="guide.migrating.postinstall.structure.run">
<title><function>run</function> メソッド</title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>run</function></funcdef>
<paramdef>array <parameter>$infoArray</parameter></paramdef>
<paramdef>string <parameter>$paramGroupId</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
<variablelist>
<varlistentry>
<term>
&type.array; <parameter>$infoArray</parameter>
</term>
<listitem>
<para>
<varname>$paramGroupId</varname> が <literal>_undoOnError</literal>
の 合、$infoArray \
には正常に終了したパラメータグループセクションの一覧が含まれます。
これを使用して、インストールスクリプトがシステ に \
えた変更を元に戻すことができます。 </para>
<para>
それ以外の 合は、<varname>$infoArray</varname>
には直近の <paramgroup>
セクションにおけるユーザの入力内容が含まれます。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
&type.string; <parameter>$paramGroupId</parameter>
</term>
<listitem>
<para>
この変数には、<literal>_undoOnError</literal> \
か、あるいは直近の
<paramgroup> の <id> タグの内容が含まれます。
paramgroup の id はアンダースコア (<literal>_</literal>)
で開始できないこと、つまり <literal>_undoOnError</literal>
は PEAR インストーラからのみ指定されることに注意しましょう。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/ja/guide/migrating/customtasks.xml?view=markup&rev=1.1
Index: peardoc/ja/guide/migrating/customtasks.xml
+++ peardoc/ja/guide/migrating/customtasks.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.4 Maintainer: takagi Status: ready -->
<chapter id="guide.migrating.customtasks">
<chapterinfo>
<author>
<firstname>Gregory</firstname>
<surname>Beaver</surname>
</author>
<date>$Date: 2007/04/22 01:38:48 $</date>
</chapterinfo>
<title>独自のファイルタスク</title>
<simpara>
多くの小規模なライブラリのパッケージでは、カスタマイズが必要になることはほとんどありません。
単にインストールすればそれで終わりです。package.xml 1.0
は、このような処理には適しています。
パッケージの規模が大きくなり複雑になってくると、ファイルの内容に少々手をいれたり
データベースなどの外部のコンポーネントを変更したりする必要が出てきます。
</simpara>
<simpara>
package.xml 1.0 では、 し機能として
<replace> タグでファイルの内容を変更することができました。
たとえばこのようになります。
</simpara>
<para>
<programlisting role="xml">
<![CDATA[
<file name="blah.php" role="php">
<replace from="@token@" to="version" type="package-info"/>
<replace from="@anothertoken@" to="php_dir" type="pear-config"/>
</file>
]]>
</programlisting>
</para>
<simpara>
上の例は、インストール時に blah.php ファイルを探し、
<ulink url="&url.php.manual;str_replace"><function>str_replace</function></ulink>
を使用してそのファイル内の文字列 <literal>@token@</literal>
をパッケージのバージョン番号に置き換えます。そして、文字列
<literal>@anothertoken@</literal> を、
php_dir の設定値に置き換えます。
</simpara>
<simpara>
これは強力な機能ではありますが、package.xml バージョン 1.0
で使用可能なカスタマイズ用タグは、この replace タグ \
けです。 package.xml バージョン 2.0 を開発するにあたって、
"task" という拡張機能を追 \
することにしました。これは <ulink url="&url.phing;">Phing</ulink> \
のような独創的な作品に影響を受けたものです。 </simpara>
<simpara>
タスクの定義は、xml の
<link linkend="guide.developers.package2.file"><file></link>
タグの子要 で行います。
タスクの実装は、<classname>PEAR_Task_Common</classname>
タスクを継承して行います。
</simpara>
<sect1 id="guide.migrating.customtasks.xml">
<title>package.xml での独自のタスクの使用</title>
<titleabbrev>package.xml における独自のタスク</titleabbrev>
<para>
タスクの定義は、package.xml の tasks \
名前空間で行います。現在は、この名前空間は <uri \
type="namespace">http://pear.php.net/dtd/tasks-1.0</uri> です。 現在の tasks \
名前空間は <ulink url="&url.pear.tasks.xsd;">&url.pear.tasks.xsd;</ulink>
で定義されています。PEAR \
にバンドルされている独自タスクには、次のようなものがあります。
</para>
<para>
<itemizedlist>
<listitem>
<para>
<link linkend="guide.developers.package2.tasks.replace"><tasks:replace></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.developers.package2.tasks.unixeol"><tasks:unixeol></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.developers.package2.tasks.windowseol"><tasks:windowseol></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.developers.package2.tasks.postinstallscript"><tasks:postinstallscript></link>
</para>
</listitem>
</itemizedlist>
</para>
<para>
これらのタスクの xml については、
<link linkend="guide.developers.package2.tasks">ここ</link>
に説明があります。
</para>
</sect1>
<sect1 id="guide.migrating.customtasks.php">
<title>PHP での独自タスクの作成</title>
<titleabbrev>独自タスクのコーディング</titleabbrev>
<para>
独自タスクを作成するためには、
xml を検証したり実際にタスクを行ったりするクラスを作成することになります。
タスクを起動する \
面としては、パッケージ作成時とインストール時のふたつがあります。
各タスクは、自分がパッケージ作成時にコールされるのかインストール時にコールされるのか、
あるいはその両方なのかを制御できます。
</para>
<para>
タスクには、単純型と複合型の二種類があります。ほとんどのタスクは単純型です。
単純型のタスクは自己完結しています。すべての処理はひとつのファイルにまとめられています。
複合型のタスクは、複数のファイルがインストールされたあとでそれらをひとまとめにして処理します。
これにより、複雑な処理ができるようになります。
</para>
<para>
必ず定義しなければならないメソッドは、
単純型のタスクでは 3 つ、複合型のタスクでは 4 \
つとなります。 以下にその内容を示します。
</para>
<para>
<itemizedlist>
<listitem>
<para>
<link linkend="guide.migrating.customtasks.php.validatexml"><function>validateXml</function></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customtasks.php.init"><function>init</function></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customtasks.php.startsession"><function>startSession</function></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customtasks.php.run"><function>run</function></link>
(複合型のタスクのみ)
</para>
</listitem>
</itemizedlist>
</para>
<sect2 id="guide.migrating.customtasks.php.validatexml">
<title><function>validateXml</function></title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>true|array <function>validateXml</function></funcdef>
<paramdef>PEAR_PackageFile_v2 <parameter>$pkg</parameter></paramdef>
<paramdef>string|array <parameter>$xml</parameter></paramdef>
<paramdef>PEAR_Config <parameter>&$config</parameter></paramdef>
<paramdef>array <parameter>$fileAttributes</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
このメソッドは package.xml の検証時にコールされ、
そのタスクの xml の内容を検証するために使用します。
エラーが発生した 合は、
<literal>array(CODE, message)</literal> \
形式の単純な配列を返す必要があります。 \
コードには以下の定数のいずれかを指定しなければなりません。これらは
<filename>PEAR/Task/Common.php</filename> で定義されています。
</para>
<para>
<itemizedlist>
<listitem>
<para>
<constant>PEAR_TASK_ERROR_NOATTRIBS</constant> -
属性を必要とすべき 所に属性が存在しません。
</para>
</listitem>
<listitem>
<para>
<constant>PEAR_TASK_ERROR_MISSING_ATTRIB</constant> -
特定の属性が存在しません。
</para>
</listitem>
<listitem>
<para>
<constant>PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE</constant> -
属性の値が無効です。
</para>
</listitem>
<listitem>
<para>
<constant>PEAR_TASK_ERROR_INVALID</constant> -
その他の検証エラー。
</para>
</listitem>
</itemizedlist>
</para>
<para>
エラーメッセージには、<literal>$fileAttributes['name']</literal>
で定義されるファイル名を含めなければなりません。
また、検証エラーが発生した 所についての情 \
も、可能なら含めておきましょう。 </para>
<para>
<variablelist>
<varlistentry>
<term>
PEAR_PackageFile_v2 <parameter>$pkg</parameter>
</term>
<listitem>
<para>
これは、タスクを含む package.xml オブジェクトです。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
string|array <parameter>$xml</parameter>
</term>
<listitem>
<para>
package.xml からパースしたタスクの xml \
の、パースした内容そのもの。
<tasks:windowseol> のように属性や子要 \
を持たないタグは、 空の文字列 <literal>''</literal> \
として渡されます。
それ以外の \
合は、単純なテキストは文字列として渡され、
タグや属性が入れ子になっている \
合は配列として渡されます。
ここで、さまざまな xml \
がどのようにパースされるかをまとめます。 </para>
<para>
<itemizedlist>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[<tasks:blah/>]]>
</programlisting>
</para>
<para>
<literal>string("");</literal>
</para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah>hello
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal>string("hello");</literal>
</para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah>hello
<tasks:boo/>
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal><![CDATA[array('_content' => 'hello', 'tasks:boo' => \
string(''))]]></literal> </para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah foo="one">
<tasks:boo/>
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal><![CDATA[
array('attribs' => array('foo' => 'one'),
'tasks:boo' => string(''))]]></literal>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
PEAR_Config <parameter>$config</parameter>
</term>
<listitem>
<para>
これは、現在の設定オブジェクトです。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
array <parameter>$fileAttributes</parameter>
</term>
<listitem>
<para>
このタグを囲む <file> タグの属性をパースしたもの。
ここには、必ず <literal>name</literal> および \
<literal>role</literal>
というインデックスが含まれ、それぞれファイル名とファイルのロールを表します。
<literal>baseinstalldir</literal> \
のようなその他の属性も存在しますが、
これは必 \
ではありません。つまり、すべてのファイルでこのような属性が存在するとは限りません。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="guide.migrating.customtasks.php.init">
<title><function>init</function></title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>init</function></funcdef>
<paramdef>string|array <parameter>$xml</parameter></paramdef>
<paramdef>array <parameter>$fileAttributes</parameter></paramdef>
<paramdef>string|null <parameter>$lastVersion</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
<function>init</function> 関数は
<function>startSession</function> メソッドの直前にコールされ、
ファイルの修正に直接かかわらない初期化作業を行います。
このメソッドは、インストールの際に別の \
所に移動する可能性があります。 \
タスクの動作と初期化作業を論理的に分割しておくことが重要で、
実行の 序がそれに依存します。
</para>
<para>
<variablelist>
<varlistentry>
<term>
string|array <parameter>$xml</parameter>
</term>
<listitem>
<para>
package.xml からパースしたタスクの xml \
の、パースした内容そのもの。
<tasks:windowseol> のように属性や子要 \
を持たないタグは、 空の文字列 <literal>''</literal> \
として渡されます。
それ以外の \
合は、単純なテキストは文字列として渡され、
タグや属性が入れ子になっている \
合は配列として渡されます。
ここで、さまざまな xml \
がどのようにパースされるかをまとめます。 </para>
<para>
<itemizedlist>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[<tasks:blah/>]]>
</programlisting>
</para>
<para>
<literal>string("");</literal>
</para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah>hello
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal>string("hello");</literal>
</para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah>hello
<tasks:boo/>
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal><![CDATA[array('_content' => 'hello', 'tasks:boo' => \
string(''))]]></literal> </para>
</listitem>
<listitem>
<para>
<programlisting role="xml">
<![CDATA[
<tasks:blah foo="one">
<tasks:boo/>
</tasks:blah>]]>
</programlisting>
</para>
<para>
<literal><![CDATA[
array('attribs' => array('foo' => 'one'),
'tasks:boo' => string(''))]]></literal>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
array <parameter>$fileAttributes</parameter>
</term>
<listitem>
<para>
このタグを囲む <file> タグの属性をパースしたもの。
ここには、必ず <literal>name</literal> および \
<literal>role</literal>
というインデックスが含まれ、それぞれファイル名とファイルのロールを表します。
<literal>baseinstalldir</literal> \
のようなその他の属性も存在しますが、
これは必 \
ではありません。つまり、すべてのファイルでこのような属性が存在するとは限りません。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
string|null <parameter>$lastVersion</parameter>
</term>
<listitem>
<para>
これは、このパッケージを最後にインストールしたときのバージョンを表す文字列を設定します。
これは、そのパッケージを更新するのか新規インストールするのかを決める際に有用です。
このパッケージを最初にインストールする際には、&null; \
が渡されます。 </para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="guide.migrating.customtasks.php.startsession">
<title><function>startSession</function></title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>string|false|PEAR_Error <function>startSession</function></funcdef>
<paramdef>string <parameter>$contents</parameter></paramdef>
<paramdef>string <parameter>$dest</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
script 以外のタスクの 合、<function>startSession</function>
をコールすると即時にタスクを実行します。
そのファイルに必要なすべての処理を行い、
成功した 合にはそのファイルの内容を \
(変更の有無にかかわらず) 返します。 \
この内容はディスクに書き込まれるので、 \
たとえファイルの内容に変更がなかったとしても元のファイルの内容をすべて返す必要があります。
</para>
<para>
script タスクの 合、<function>startSession</function>
をコールするとそのスクリプトが安全に実行できるかどうかを調べます。
script タスクとそれ以外のタスクのどちらの \
合についても、もし返り値が &false; \
であればそのタスクの処理を黙って飛ばします。 返り値が \
PEAR_Error の 合は、すべての処理を停止します。 \
インストーラが処理を停止する前に、エラーメッセージを出力します。
その他の返り値の \
合はスクリプトの処理は通常どおりに進み、 \
インストール後のスクリプトが実行されます。 </para>
<para>
<variablelist>
<varlistentry>
<term>
string <parameter>$contents</parameter>
</term>
<listitem>
<para>
package.xml 内で task タグを含む <file>
タグについて、元のファイルの内容。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
string <parameter>$dest</parameter>
</term>
<listitem>
<para>
最終的にファイルがインストールされる \
所へのフルパス。
これは厳密には単なる情 \
としての意味しかありません。 というのもファイルはま \
そこには存在せず、 エラーメッセージや \
(ファイルの変更を伴わない)
その他の処理のためにのみ使用するもの からです。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="guide.migrating.customtasks.php.run">
<title><function>run</function></title>
<para>
<funcsynopsis>
<funcprototype>
<funcdef>false|string <function>run</function></funcdef>
<paramdef>array <parameter>$tasks</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</para>
<para>
<function>run</function> メソッドは、成功した 合に &false;
を返します。問題が発生した \
合にはエラーメッセージを返します。 \
このメソッドは、<varname>$this->type</varname> が \
<literal>multiple</literal> \
であるタスクについてのみコールされます。 \
このタスクを持つ package.xml 内の各タスクについて、 package.xml \
のすべてのタスクの内容を含む配列を渡して \
<function>run</function> メソッドがコールされます。 </para>
<para>
<variablelist>
<varlistentry>
<term>
array <parameter>$tasks</parameter>
</term>
<listitem>
<para>
タスクオブジェクトの配列。
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/ja/guide/migrating/customroles.xml?view=markup&rev=1.1
Index: peardoc/ja/guide/migrating/customroles.xml
+++ peardoc/ja/guide/migrating/customroles.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.4 Maintainer: takagi Status: ready -->
<chapter id="guide.migrating.customroles">
<chapterinfo>
<author>
<firstname>Gregory</firstname>
<surname>Beaver</surname>
</author>
<date>$Date: 2007/04/22 01:38:48 $</date>
</chapterinfo>
<title>独自のロール</title>
<warning>
<simpara>
PEAR バージョン 1.4.3 \
で、セキュリティ上の脆弱性に対応するため \
ファイルロールの書式が変更されました。 \
独自のファイルロールは、<filename>Role.xml</filename> \
ファイルで適切に宣言しなければなりません。 詳細な情 \
は、以下の例を参照く さい。 </simpara>
</warning>
<simpara>
PEAR インストーラが強制する機能として、
ファイルをカテゴリに分類することがあります。
同じカテゴリのファイルは、常に同じ \
所にインストールされます。 \
あるいは少なくとも同じ方法で処理されます。たとえば PECL \
パッケージなら role="src" となります。 </simpara>
<simpara>
これは、ライブラリ形式の小さめのパッケージでは非常にうまく機能していました。
しかし、完全なアプリケーションでは、インストールの \
所を変更できなければいけません。 \
たとえば、いくつかのファイルはウェブに公開し、 \
その他のファイルはライブラリとして使用するといったことがあります。
PEAR 1.4 では、独自のインストールロールを定義することで
これに対応できるようになりました。
</simpara>
<sect1 id="guide.migrating.customroles.xml">
<title>package.xml での独自のロールの使用</title>
<titleabbrev>package.xml での独自ロール</titleabbrev>
<para>
別のプログラマが書いた独自のインストールロールを使用するために必要な手 \
は、次の三つです。 まず、
<link linkend="guide.developers.package2.usesrole"><usesrole></link>
タグを使用し、package.xml \
内で用いるロールを定義する必要があります。 \
次に、そのロールは、単純にそれが属するファイル内でのみ使用しなければなりません。
最後に、独自のロールを提供するパッケージについての依存性情 \
を package.xml に追 \
しなければなりません。これは単に完全を期すためのものです。
</para>
<para>
単純なことです!
</para>
</sect1>
<sect1 id="guide.migrating.customroles.defining">
<title>package.xml で使用する独自のロールの定義</title>
<titleabbrev>独自のロールの作成</titleabbrev>
<para>
独自のロールを定義するには、ひとつのファイルからなるパッケージを作成する必要があります。
独自のロールを定義する package.xml の例を示します。
</para>
<para>
<programlisting role="xml">
<![CDATA[
<?xml version="1.0"?>
<package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
http://pear.php.net/dtd/tasks-1.0.xsd
http://pear.php.net/dtd/package-2.0
http://pear.php.net/dtd/package-2.0.xsd">
<name>Chiarafoo</name>
<channel>pear.chiaraquartet.net</channel>
<summary>Chiarafoo role</summary>
<description>
The chiarafoo role installs files into your customized Foo directory
</description>
<lead>
<name>Greg Beaver</name>
<user>cellog</user>
<email>cellog@php.net</email>
<active>yes</active>
</lead>
<date>2005-03-21</date>
<version>
<release>1.0.0</release>
<api>1.0.0</api>
</version>
<stability>
<release>stable</release>
<api>stable</api>
</stability>
<license uri="http://www.php.net/license">PHP License</license>
<notes>
Provides the chiarafoo file role
</notes>
<contents>
<dir name="/" baseinstalldir="PEAR/Installer/Role">
<file name="Chiarafoo.xml" role="php"/>
<file name="Chiarafoo.php" role="php">
<tasks:replace from="@package_version@" to="version" type="package-info"/>
</file>
</dir> <!-- / -->
</contents>
<dependencies>
<required>
<php>
<min>4.2.0</min>
</php>
<pearinstaller>
<min>1.4.3</min>
</pearinstaller>
</required>
</dependencies>
<phprelease/>
</package>
]]>
</programlisting>
</para>
<para>
XML ファイル Chiarafoo.xml は、このようになります。
</para>
<para>
<programlisting role="xml">
<![CDATA[
<role version="1.0">
<releasetypes>php</releasetypes>
<installable>1</installable>
<locationconfig>foo_dir</locationconfig>
<honorsbaseinstall>1</honorsbaseinstall>
<unusualbaseinstall />
<phpfile>1</phpfile>
<executable />
<phpextension />
<config_vars>
<foo_dir>
<type>directory</type>
<default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>
<doc>directory where foo files are installed</doc>
<prompt>PHP foo directory</prompt>
<group>File Locations</group>
</foo_dir>
</config_vars>
</role>
]]>
</programlisting>
</para>
<para>
Chiarafoo.php のスクリプトは、信じられないくらいシンプルです。
</para>
<para>
<programlisting role="php">
<![CDATA[
<?php
/**
* PEAR_Installer_Role_Chiarafoo
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category pear
* @package Chiarafoo
* @author Greg Beaver <cellog@php.net>
* @copyright 2005 Greg Beaver
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id: customroles.xml,v 1.1 2007/04/22 01:38:48 takagi Exp $
* @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo
* @since File available since Release 0.1.0
*/
/**
* @category pear
* @package Chiarafoo
* @author Greg Beaver <cellog@php.net>
* @copyright 2005 Greg Beaver
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.chiaraquartet.net/index.php?package=Chiarafoo
* @since Class available since Release 0.1.0
*/
class PEAR_Installer_Role_Chiarafoo extends PEAR_Installer_Role_Common
{
/**
* @param PEAR_Installer
* @param PEAR_PackageFile_v2
* @param array file attributes
* @param string relative path to file in package.xml
*/
function setup(&$installer, $pkg, $atts, $file)
{
// インストーラで、何か特別なことをします
}
}
?>
]]>
</programlisting>
</para>
<para>
PEAR 1.4.3 以降では、最低限これ \
けあればファイルのロールを実装できます。 </para>
<para>
ロールの XML ファイルには、これらのタグが含まれる必要があります。
<itemizedlist>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.releasetypes"><releasetypes></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.installable"><installable></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.locationconfig"><locationconfig></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.honorsbaseinstall"><honorsbaseinstall></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.unusualbaseinstall"><unusualbaseinstall></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.phpfile"><phpfile></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.executable"><executable></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.phpextension"><phpextension></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="guide.migrating.customroles.defining.config-vars">(optional) \
<config_vars></link> </para>
</listitem>
</itemizedlist>
</para>
<sect2 id="guide.migrating.customroles.defining.releasetypes">
<title><releasetypes> タグ</title>
<para>
このタグは、以下のいずれかの値のみを含むことができます。
</para>
<para>
<itemizedlist>
<listitem>
<para>
x php
</para>
</listitem>
<listitem>
<para>
extsrc
</para>
</listitem>
<listitem>
<para>
extbin
</para>
</listitem>
</itemizedlist>
</para>
<para>
複数のリリースタイプとの互換性を指定するには、このようにして複数の
<releasetypes> タグを指定します。
</para>
<para>
<programlisting role="xml">
<![CDATA[
<releasetypes>php</releasetypes>
<releasetypes>extsrc</releasetypes>
<releasetypes>extbin</releasetypes>
]]>
</programlisting>
</para>
<para>
releasetypes は、このロールを使用できるリリースの種類を定義します。
たとえば "src" ロールは extsrc \
パッケージに予約されており、 通常の PEAR 形式の php \
リリースでは使用できません。 "data" ロールは
<releasetypes> \
を次のように定義しているので、任意のリリースで使用できます。
</para>
<para>
<programlisting role="php">
<![CDATA[
<releasetypes>php</releasetypes>
<releasetypes>extsrc</releasetypes>
<releasetypes>extbin</releasetypes>
]]>
</programlisting>
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.installable">
<title><installable> タグ</title>
<para>
このタグは、<installable>1</installable> あるいは空タグ
(<installable/>) のいずれかでなければなりません。
このカスタ \
ロールを使用するファイルがインストール可能かどうかを示します。
インストールする必要のあるファイルは、これを 1 \
に設定しなければなりません。 \
これを空タグに設定しなければならないのは、たとえば \
"src" ロールなど、インストール用のファイルを作成するために使用するロール \
けです。 </para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.locationconfig">
<title><locationconfig> タグ</title>
<para>
このタグは、すべてのインストール可能なファイルで使用します。
これは、ファイルをインストールするディレクトリを含む設定変数がどれであるのかを示します。
たとえば php ファイルは "php_dir"、data \
ロールのファイルは "data_dir" の設定を使用します。
</para>
<para>
今回のサンプルのロールである chiarafoo では、設定変数 \
"foo_dir" を使用するようにします。 <config_vars> \
の定義を使用して、インストーラに foo_dir \
の意味を知らせます。 このカスタ \
ロールをインストールすると、その他の設定変数と同様に \
config-set/config-get/config-show を使用できるようになります。 </para>
<para>
<config_vars> \
では複数の設定変数を定義することができます。 しかし 3 \
つより多くの変数を指定するとエラーを引き起こし、それらをすべて無効にします。
これはセキュリティ上の予防措置です。
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.honorsbaseinstall">
<title><honorsbaseinstall> タグ</title>
<para>
このタグは、そのロールが <file> あるいは <dir> \
タグの "baseinstalldir" \
属性に反応するかどうかを指定します。 baseinstalldir \
を使用するロールの 合、 \
別々のパッケージからのファイルが競合する可能性があります。
そこで、競合のチェックが必要となります。
baseinstalldir を使用しないファイルは、常に以下の \
所にインストールされます。 </para>
<para>
<filename>Packagename/full/path/from/contents/file.ext</filename>
</para>
<para>
この値を指定するには
<honorsbaseinstall>1</honorsbaseinstall>
とします。指定しない 合は、空のタグ \
(<honorsbaseinstall/>) にしなければなりません。
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.unusualbaseinstall">
<title><unusualbaseinstall> タグ</title>
<para>
このタグは、そのロールが <file> あるいは <dir> \
タグの "baseinstalldir" 属性を無視し、
<filename>baseinstalldir/full/path/from/contents/file.ext</filename> \
の代わりに <filename>Packagename/baseinstalldir/full/path/from/contents/file.ext</filename>
を使用するかどうかを指定します。
unusual baseinstalldir 型をサポートするロールは、
他のファイルと競合することができません。
パッケージ名が常に親ディレクトリとなるからです。
この値を指定するには \
<unusualbaseinstall>1</unusualbaseinstall> \
とします。それ以外の 合は、空のタグ (<unusualbaseinstall/>) \
でなければなりません。 </para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.phpfile">
<title><phpfile> タグ</title>
<para>
php スクリプトファイルを含むロールでは、このタグを 1 \
に設定 (<phpfile>1</phpfile>) しなければなりません。
これらのファイルはパッケージ作成時に解析され、リリース前にエラーを発見します。
その他の 合は、空のタグ
(<phpfile/>) にしなければなりません。
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.executable">
<title><executable> タグ</title>
<para>
"script" ロールのように、インストール時に \
<function>chmod</function> \
で実行属性を指定する必要のあるロールでは、このタグを 1 \
に設定 (<executable>1</executable>) しなければなりません。
その他の 合は、空のタグ
(<executable/>) にしなければなりません。
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.phpextension">
<title><phpextension> タグ</title>
<para>
このタグは、"ext" ロールのように
PHP のバイナリ拡張モジュールを提供するロールに対して使用します。この値を指定するには
<phpextension>1</phpextension> とします。
その他の 合は、空のタグ
(<phpextension/>) にしなければなりません。
</para>
</sect2>
<sect2 id="guide.migrating.customroles.defining.config-vars">
<title>オプションの <config_vars> タグ</title>
<para>
このタグは、そのロールがインストーラに追 \
する設定変数を指定するために使用します。 \
インストーラでは、ひとつのロールが 3 \
つを超える設定変数を作成できないようにしていることに注意しましょう。
設定変数を定義するには、その設定変数の名前のタグを作成し、
その内部のタグで設定変数についての情 を定義します。
</para>
<para>
これらのタグは、PEAR_Config で使用できる形式の PHP \
の配列に変換されます。 この変換には、Stephan Schmidt \
が作成したすばらしい <classname>XML_Unserializer</classname> クラス \
(XML_Serializer パッケージに含まれます) を改 \
したものを使用しています。 XML \
の書式について理解するには、既存の設定変数を調べてみるのがもっともわかりやすいでしょう。
</para>
<para>
<programlisting role="php">
<![CDATA[
array(
'password' => array(
'type' => 'password',
'default' => '',
'doc' => '(maintainers) your PEAR account password',
'prompt' => 'PEAR password (for maintainers)',
'group' => 'Maintainers',
),
// Advanced
'verbose' => array(
'type' => 'integer',
'default' => PEAR_CONFIG_DEFAULT_VERBOSE,
'doc' => 'verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug',
'prompt' => 'Debug Log Level',
'group' => 'Advanced',
),
'preferred_state' => array(
'type' => 'set',
'default' => PEAR_CONFIG_DEFAULT_PREFERRED_STATE,
'doc' => 'the installer will prefer releases with this state when \
installing packages without a version or state specified', 'valid_set' => array(
'stable', 'beta', 'alpha', 'devel', 'snapshot'),
'prompt' => 'Preferred Package State',
'group' => 'Advanced',
),
);
]]>
</programlisting>
</para>
<para>
これらのサンプル設定値は実際の PEAR_Config \
クラスのもので、 これは次のような XML に変換されます。
</para>
<para>
<programlisting role="xml">
<![CDATA[
<config_vars>
<password>
<type>password</type>
<default />
<doc>(maintainers) your PEAR account password'</doc>
<prompt>PEAR password (for maintainers)</prompt>
<group>Maintainers</group>
</password>
<verbose>
<type>integer</type>
<default><constant>PEAR_CONFIG_DEFAULT_VERBOSE</constant></default>
<doc>verbosity level
0: really quiet
1: somewhat quiet
2: verbose
3: debug</doc>
<prompt>Debug Log Level</prompt>
<group>Advanced</group>
</verbose>
<preferred_state>
<type>set</type>
<default><constant>PEAR_CONFIG_DEFAULT_PREFERRED_STATE</constant></default>
<doc>the installer will prefer releases with this state when installing packages \
without a version or state specified</doc> <valid_set>stable</valid_set>
<valid_set>beta</valid_set>
<valid_set>alpha</valid_set>
<valid_set>devel</valid_set>
<valid_set>snapshot</valid_set>
<prompt>Preferred Package State</prompt>
<group>Advanced</group>
</preferred_state>
</config_vars>
]]>
</programlisting>
</para>
<para>
有効な値を定義する単純な配列が、設定変数 preferred_state
の個別の <valid_set> \
タグに変換されていることに注意しましょう。 </para>
<para>
<default> タグの値には、単純な文字列かあるいは以下の三種類のタグを指定します。
<itemizedlist>
<listitem>
<para>
<text> - これは、PHP の文字列に変換されます。
</para>
</listitem>
<listitem>
<para>
<constant> - このタグの内容は、
定義済みの PHP 定数あるいは PEAR 定数
(PEAR_Config や PEAR_Common で定義されているもの)
を取得してそれを <constant> \
タグで置き換えるために使用します。 </para>
</listitem>
<listitem>
<para>
任意のデフォルト設定変数。
たとえば default_channel、
preferred_mirror、remote_config、auto_discover、master_server、
http_proxy、php_dir、ext_dir、doc_dir、bin_dir、data_dir、
test_dir、cache_dir、php_bin、username、password、verbose、
preferred_state、umask、cache_ttl、sig_type、sig_bin、sig_keyid
および sig_keydir が含まれます。
</para>
<para>
これらを使用する 合、設定変数は
<php_dir/> のような空のタグとなります。
このタグは、設定変数の <emphasis>デフォルト</emphasis>
値で置き換えられます。現在代入されている値 \
<emphasis>ではありません</emphasis>。 </para>
</listitem>
</itemizedlist>
</para>
<para>
たとえば、この例のデフォルト値である
</para>
<para>
<programlisting role="xml">
<![CDATA[
<default><text0>hi there </text0><constant>PHP_OS</constant><text1> user, your \
default php_dir is </text1><php_dir/></default> ]]>
</programlisting>
</para>
<para>
は、"hi there Linux user, your default php_dir is
/usr/local/lib/php/pear" のように変換されます。
</para>
<para>
今回の例の Chiarafoo ロールにおける foo_dir のデフォルト値
<programlisting role="xml">
<![CDATA[
<default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>
]]>
</programlisting>
</para>
<para>
は、"/usr/local/lib/php/Foo" あるいは
"C:\php5\pear\Foo" のように変換されます。
</para>
<para>
複数の <constant> タグや <text> タグを使用するには、
上の例のように最後に数値を追 して <text0> <text1>
のようにしなければならないことに注意しましょう。
デフォルト値として使用できるのは、PEAR の設定変数 \
けです。 </para>
<para>
<type>integer</type> を使用する 合は、
どんなデフォルト値を指定したとしても PEAR_Config
で integer にキャストされることに注意しましょう。
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic