Creating customized tasks in PHP

Creating a custom task involves creating a class that validates xml, and performs the task when called upon. Tasks can be invoked in two situations: at package-time and at install-time. Each task can control whether it should be called at package-time, install-time, or at both times.

There are two kinds of tasks: simple and multiple. Most tasks are simple tasks. Simple tasks are self-contained: all customization is limited to that file. Multiple tasks are collected during installation and processed fully as a unit after files have been committed to disk, allowing more complex processing.

All simple tasks must define 3 methods, all multiple tasks must define 4 methods. These are:

validateXml()

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

This method is called upon package.xml validation and should be used to validate the task's xml content. Upon error, a simple array of format array(CODE, message) must be returned. The code must be one of the following constants, as defined in PEAR/Task/Common.php:

PEAR_TASK_ERROR_NOATTRIBS - Attributes were expected, but none were present.
PEAR_TASK_ERROR_MISSING_ATTRIB - A specific attribute is not present.
PEAR_TASK_ERROR_WRONG_ATTRIB_VALUE - The value of an attribute is incorrect.
PEAR_TASK_ERROR_INVALID - Any other error in validation.

The error message should include the file name as defined by $fileAttributes['name'], and include as much useful information about the location of the validation error as possible.

PEAR_PackageFile_v2 $pkg: This is the package.xml object that contains the task.

string|array $xml

The raw parsed content of the task's xml as parsed from package.xml. Tags like <tasks:windowseol> that have no attributes or child elements will be passed an empty string ''. Otherwise, simple text content will be a string, and nested tags/attributes will be passed in as an array. Here is a list of sample xml and their parsed values:

```
<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: This is the current configuration object

array $fileAttributes: The parsed attributes of the <file> tag that encloses this tag. This is guaranteed to contain indices name, specifying the file name, and role, specifying the file role. Other attributes like baseinstalldir may be present but are not required, and so will not be guaranteed to be present for every file.

init()

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

The init() function is called immediately prior to the startSession() method, and should be used for initialization that is not directly related to file modification. This method may move to another location in the installation process at any time. The logical separation of initialization from task action is important and the order of execution can be depended upon.

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: The parsed attributes of the <file> tag that encloses this tag. This is guaranteed to contain indices name, specifying the file name, and role, specifying the file role. Other attributes like baseinstalldir may be present but are not required, and so will not be guaranteed to be present for every file.

string|null $lastVersion: This will be set to the string representing the version of the last installed version of this package. This is useful for determining whether the package is being upgraded or is a fresh installation. If the package is being installed for the first time, NULL will be passed in.

startSession()

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

For non-script tasks, startSession() is called to actually execute a task. The task should perform all needed operations on the file contents, and on success return the file contents regardless of any modification. These contents will be written to disk, so it is imperative that they be the full, original file contents if no modification is made to them.

For script tasks, startSession() is called to determine whether the script can be safely executed. For both task types, script and non-script, a return value of FALSE will cause the task to be silently skipped. A return value of a PEAR_Error will cause processing of all operations to stop, and an error message to be displayed by the installer prior to exiting. Any other return value will cause the script to be processed normally by the frontend as a post-installation script.

string $contents: The original contents of the file whose <file> tag in package.xml contains the task tag.

string $dest: The full path to the final installed file location. This is strictly informational, as the file does not yet exist, and should only be used for error messages or other processing that does not attempt to modify the file.

run()

false|string run ( array $tasks )

The run() method should return FALSE on success, and an error message if there is a problem. This method is called only for tasks that define $this->type as multiple. For each task within package.xml that has this task, the run() method will be called with an array containing all of the task objects from the package.xml.

array $tasks: An array of task objects.

Creating customized tasks in PHP

validateXml()

init()

startSession()

run()

User Notes: