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 task must define 4 methods.
These are:
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:
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.
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
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:
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.
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.
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.
