Creating customized tasks in PHP

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

validateXml()

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

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:

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

© Copyright 2003-2014 www.php-editors.com. The ultimate PHP Editor and PHP IDE site.