package.xml で使用する独自のロールの定義

独自のロールを定義するには、ひとつのファイルからなるパッケージを作成する必要があります。 独自のロールを定義する package.xml の例を示します。

<?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>

XML ファイル Chiarafoo.xml は、このようになります。

<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>

Chiarafoo.php のスクリプトは、信じられないくらいシンプルです。

<?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)
    {
        // インストーラで、何か特別なことをします
    }
}
?>

PEAR 1.4.3 以降では、最低限これだけあればファイルのロールを実装できます。

ロールの XML ファイルには、これらのタグが含まれる必要があります。

<releasetypes> タグ

このタグは、以下のいずれかの値のみを含むことができます。

複数のリリースタイプとの互換性を指定するには、このようにして複数の <releasetypes> タグを指定します。

<releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>

releasetypes は、このロールを使用できるリリースの種類を定義します。 たとえば "src" ロールは extsrc パッケージに予約されており、 通常の PEAR 形式の php リリースでは使用できません。 "data" ロールは <releasetypes> を次のように定義しているので、任意のリリースで使用できます。

<releasetypes>php</releasetypes>
 <releasetypes>extsrc</releasetypes>
 <releasetypes>extbin</releasetypes>

<installable> タグ

このタグは、<installable>1</installable> あるいは空タグ (<installable/>) のいずれかでなければなりません。 このカスタムロールを使用するファイルがインストール可能かどうかを示します。 インストールする必要のあるファイルは、これを 1 に設定しなければなりません。 これを空タグに設定しなければならないのは、たとえば "src" ロールなど、インストール用のファイルを作成するために使用するロールだけです。

<locationconfig> タグ

このタグは、すべてのインストール可能なファイルで使用します。 これは、ファイルをインストールするディレクトリを含む設定変数がどれであるのかを示します。 たとえば php ファイルは "php_dir"、data ロールのファイルは "data_dir" の設定を使用します。

今回のサンプルのロールである chiarafoo では、設定変数 "foo_dir" を使用するようにします。 <config_vars> の定義を使用して、インストーラに foo_dir の意味を知らせます。 このカスタムロールをインストールすると、その他の設定変数と同様に config-set/config-get/config-show を使用できるようになります。

<config_vars> では複数の設定変数を定義することができます。 しかし 3 つより多くの変数を指定するとエラーを引き起こし、それらをすべて無効にします。 これはセキュリティ上の予防措置です。

<honorsbaseinstall> タグ

このタグは、そのロールが <file> あるいは <dir> タグの "baseinstalldir" 属性に反応するかどうかを指定します。 baseinstalldir を使用するロールの場合、 別々のパッケージからのファイルが競合する可能性があります。 そこで、競合のチェックが必要となります。 baseinstalldir を使用しないファイルは、常に以下の場所にインストールされます。

Packagename/full/path/from/contents/file.ext

この値を指定するには <honorsbaseinstall>1</honorsbaseinstall> とします。指定しない場合は、空のタグ (<honorsbaseinstall/>) にしなければなりません。

<unusualbaseinstall> タグ

このタグは、そのロールが <file> あるいは <dir> タグの "baseinstalldir" 属性を無視し、 baseinstalldir/full/path/from/contents/file.ext の代わりに Packagename/baseinstalldir/full/path/from/contents/file.ext を使用するかどうかを指定します。 unusual baseinstalldir 型をサポートするロールは、 他のファイルと競合することができません。 パッケージ名が常に親ディレクトリとなるからです。 この値を指定するには <unusualbaseinstall>1</unusualbaseinstall> とします。それ以外の場合は、空のタグ (<unusualbaseinstall/>) でなければなりません。

<phpfile> タグ

php スクリプトファイルを含むロールでは、このタグを 1 に設定 (<phpfile>1</phpfile>) しなければなりません。 これらのファイルはパッケージ作成時に解析され、リリース前にエラーを発見します。 その他の場合は、空のタグ (<phpfile/>) にしなければなりません。

<executable> タグ

"script" ロールのように、インストール時に chmod() で実行属性を指定する必要のあるロールでは、このタグを 1 に設定 (<executable>1</executable>) しなければなりません。 その他の場合は、空のタグ (<executable/>) にしなければなりません。

<phpextension> タグ

このタグは、"ext" ロールのように PHP のバイナリ拡張モジュールを提供するロールに対して使用します。この値を指定するには <phpextension>1</phpextension> とします。 その他の場合は、空のタグ (<phpextension/>) にしなければなりません。

オプションの <config_vars> タグ

このタグは、そのロールがインストーラに追加する設定変数を指定するために使用します。 インストーラでは、ひとつのロールが 3 つを超える設定変数を作成できないようにしていることに注意しましょう。 設定変数を定義するには、その設定変数の名前のタグを作成し、 その内部のタグで設定変数についての情報を定義します。

これらのタグは、PEAR_Config で使用できる形式の PHP の配列に変換されます。 この変換には、Stephan Schmidt が作成したすばらしい XML_Unserializer クラス (XML_Serializer パッケージに含まれます) を改造したものを使用しています。 XML の書式について理解するには、既存の設定変数を調べてみるのがもっともわかりやすいでしょう。

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',
            ),
         );

これらのサンプル設定値は実際の PEAR_Config クラスのもので、 これは次のような XML に変換されます。

<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>

有効な値を定義する単純な配列が、設定変数 preferred_state の個別の <valid_set> タグに変換されていることに注意しましょう。

<default> タグの値には、単純な文字列かあるいは以下の三種類のタグを指定します。

たとえば、この例のデフォルト値である

<default><text0>hi there </text0><constant>PHP_OS</constant><text1> user, your default php_dir is </text1><php_dir/></default>

は、"hi there Linux user, your default php_dir is /usr/local/lib/php/pear" のように変換されます。

今回の例の Chiarafoo ロールにおける foo_dir のデフォルト値
<default><php_dir/><constant>DIRECTORY_SEPARATOR</constant><text>Foo</text></default>

は、"/usr/local/lib/php/Foo" あるいは "C:\php5\pear\Foo" のように変換されます。

複数の <constant> タグや <text> タグを使用するには、 上の例のように最後に数値を追加して <text0> <text1> のようにしなければならないことに注意しましょう。 デフォルト値として使用できるのは、PEAR の設定変数だけです。

<type>integer</type> を使用する場合は、 どんなデフォルト値を指定したとしても PEAR_Config で integer にキャストされることに注意しましょう。