PHP での独自タスクの作成

独自タスクを作成するためには、 xml を検証したり実際にタスクを行ったりするクラスを作成することになります。タスクを起動する場面としては、パッケージ作成時とインストール時のふたつがあります。各タスクは、自分がパッケージ作成時にコールされるのかインストール時にコールされるのか、あるいはその両方なのかを制御できます。

タスクには、単純型と複合型の二種類があります。ほとんどのタスクは単純型です。単純型のタスクは自己完結しています。すべての処理はひとつのファイルにまとめられています。複合型のタスクは、複数のファイルがインストールされたあとでそれらをひとまとめにして処理します。これにより、複雑な処理ができるようになります。

必ず定義しなければならないメソッドは、単純型のタスクでは 3 つ、複合型のタスクでは 4 つとなります。以下にその内容を示します。

validateXml()
init()
startSession()
run() (複合型のタスクのみ)

validateXml()

true|array validateXml ( PEAR_PackageFile_v2 $pkg , string|array $xml , PEAR_Config &$config , array $fileAttributes )

このメソッドは package.xml の検証時にコールされ、そのタスクの xml の内容を検証するために使用します。エラーが発生した場合は、 array(CODE, message) 形式の単純な配列を返す必要があります。コードには以下の定数のいずれかを指定しなければなりません。これらは PEAR/Task/Common.php で定義されています。

PEAR_TASK_ERROR_NOATTRIBS - 属性を必要とすべき場所に属性が存在しません。
PEAR_TASK_ERROR_MISSING_ATTRIB - 特定の属性が存在しません。
PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE - 属性の値が無効です。
PEAR_TASK_ERROR_INVALID - その他の検証エラー。

エラーメッセージには、$fileAttributes['name'] で定義されるファイル名を含めなければなりません。また、検証エラーが発生した場所についての情報も、可能なら含めておきましょう。

PEAR_PackageFile_v2 $pkg: これは、タスクを含む package.xml オブジェクトです。

string|array $xml

package.xml からパースしたタスクの xml の、パースした内容そのもの。 <tasks:windowseol> のように属性や子要素を持たないタグは、空の文字列 '' として渡されます。それ以外の場合は、単純なテキストは文字列として渡され、タグや属性が入れ子になっている場合は配列として渡されます。ここで、さまざまな xml がどのようにパースされるかをまとめます。

```
<tasks:blah/>
```
string("");
```
<tasks:blah>hello
</tasks:blah>
```
string("hello");
```
<tasks:blah>hello
 <tasks:boo/>
</tasks:blah>
```
array('_content' => 'hello', 'tasks:boo' => string(''))
```
<tasks:blah foo="one">
 <tasks:boo/>
</tasks:blah>
```
array('attribs' => array('foo' => 'one'), 'tasks:boo' => string(''))

PEAR_Config $config: これは、現在の設定オブジェクトです。

array $fileAttributes: このタグを囲む <file> タグの属性をパースしたもの。ここには、必ず name および role というインデックスが含まれ、それぞれファイル名とファイルのロールを表します。 baseinstalldir のようなその他の属性も存在しますが、これは必須ではありません。つまり、すべてのファイルでこのような属性が存在するとは限りません。

init()

void init ( string|array $xml , array $fileAttributes , string|null $lastVersion )

init() 関数は startSession() メソッドの直前にコールされ、ファイルの修正に直接かかわらない初期化作業を行います。このメソッドは、インストールの際に別の場所に移動する可能性があります。タスクの動作と初期化作業を論理的に分割しておくことが重要で、実行の順序がそれに依存します。

string|array $xml

```
<tasks:blah/>
```
string("");
```
<tasks:blah>hello
</tasks:blah>
```
string("hello");
```
<tasks:blah>hello
 <tasks:boo/>
</tasks:blah>
```
array('_content' => 'hello', 'tasks:boo' => string(''))
```
<tasks:blah foo="one">
 <tasks:boo/>
</tasks:blah>
```
array('attribs' => array('foo' => 'one'), 'tasks:boo' => string(''))

array $fileAttributes: このタグを囲む <file> タグの属性をパースしたもの。ここには、必ず name および role というインデックスが含まれ、それぞれファイル名とファイルのロールを表します。 baseinstalldir のようなその他の属性も存在しますが、これは必須ではありません。つまり、すべてのファイルでこのような属性が存在するとは限りません。

string|null $lastVersion: これは、このパッケージを最後にインストールしたときのバージョンを表す文字列を設定します。これは、そのパッケージを更新するのか新規インストールするのかを決める際に有用です。このパッケージを最初にインストールする際には、NULL が渡されます。

startSession()

string|false|PEAR_Error startSession ( string $contents , string $dest )

script 以外のタスクの場合、startSession() をコールすると即時にタスクを実行します。そのファイルに必要なすべての処理を行い、成功した場合にはそのファイルの内容を (変更の有無にかかわらず) 返します。この内容はディスクに書き込まれるので、たとえファイルの内容に変更がなかったとしても元のファイルの内容をすべて返す必要があります。

script タスクの場合、startSession() をコールするとそのスクリプトが安全に実行できるかどうかを調べます。 script タスクとそれ以外のタスクのどちらの場合についても、もし返り値が FALSE であればそのタスクの処理を黙って飛ばします。返り値が PEAR_Error の場合は、すべての処理を停止します。インストーラが処理を停止する前に、エラーメッセージを出力します。その他の返り値の場合はスクリプトの処理は通常どおりに進み、インストール後のスクリプトが実行されます。

string $contents: package.xml 内で task タグを含む <file> タグについて、元のファイルの内容。

string $dest: 最終的にファイルがインストールされる場所へのフルパス。これは厳密には単なる情報としての意味しかありません。というのもファイルはまだそこには存在せず、エラーメッセージや (ファイルの変更を伴わない) その他の処理のためにのみ使用するものだからです。

run()

false|string run ( array $tasks )

run() メソッドは、成功した場合に FALSE を返します。問題が発生した場合にはエラーメッセージを返します。このメソッドは、$this->type が multiple であるタスクについてのみコールされます。このタスクを持つ package.xml 内の各タスクについて、 package.xml のすべてのタスクの内容を含む配列を渡して run() メソッドがコールされます。

array $tasks: タスクオブジェクトの配列。

各種マニュアル： PHPマニュアル \| PEARマニュアル \| Smarty(英語)マニュアル \| PHP-GTKマニュアル \| 「独自タスクのコーディング」をGoogle検索
copyright © 1997-2024 PHP ドキュメント作成グループ(ライセンス). provided by php spot.	マニュアル：