Tasks provide a flexible and customizable way to manipulate file contents or to perform complex installation tasks (hence the name "tasks"). By default, PEAR comes with 4 tasks, but customized tasks can be added simply by adding a file into the PEAR/Tasks directory that follows the conventions of existing tasks. This page does not describe how to create a custom task, only how to use them in package.xml.
There are 3 basic tasks and 1 complex task distributed with PEAR. The basic tasks are "tasks:replace", "tasks:windowseol", and "tasks:unixeol". The complex task is "tasks:postinstallscript". "tasks:replace" is nearly identical to the old <replace> tag from package.xml 1.0, and does a text search-and-replace of a file's contents. "tasks:windowseol" and "tasks:unixeol" manipulate the line endings of a file to ensure that the correct line endings are in place for critical files like DOS .bat batch files and unix shell scripts. "tasks:postinstallscript" allows users to choose to run a script to perform further installation functions.
The replace task has 3 required attributes:
type - This must be either package-info or pear-config. package-info replacements extract information from package.xml itself to use as the replacement text. pear-config replacements use the value of a configuration variable (as displayed by
pear config-show |
from - Text to search for in a file. Traditionally, this text is enclosed in "@" to differentiate it from normal text, as in from="@version@"
to - Abstract item to use as a replacement for all occurences of "from". package-info replacements can be one of version, release_date, release_state, release_license, release_notes, apiversion, name, summary, description, notes, time, date, and for some packages extends, srcpackage, srcuri, and providesextension.
Note that package-info replacements are performed at packaging time, so files contain package-info replacements inside a .tgz/.tar release. pear-config replacements can only occur on the installation system, and are performed at install-time.
This task can be used to enable packaging of windows-specific files (like DOS batch files) on a non-windows system, such as unix systems that convert line endings to \n. Note that this task is performed at package-time, as well as at install-time, so files will contain the correct line endings inside a .tgz/.tar release.
This task can be used to enable packaging of unix-specific files (like sh shell scripts) on a non-unix system, such as windows systems that convert line endings to \r\n. Note that this task is performed at package-time, as well as at install-time, so files will contain the correct line endings inside a .tgz/.tar release.
The postinstallscript task informs the installer that the file it references is a post-installation script.
For security reasons, post-install scripts must be manually executed by the users, and as such the installer has special code that is separate from other tasks.
The <postinstallscript> tag may define parameters that are used by the installer to retrieve user input. In order to support both the web installer and the command-line installer, all processing of input is performed by PEAR and passed to the post-install script in a strict format. All you need to do is define the parameters using xml inside the <postinstallscript> tag.
Here is the xml representing a simple post-install script with parameters:
<tasks:postinstallscript> <tasks:paramgroup> <tasks:id>first</tasks:id> <tasks:param> <tasks:name>test</tasks:name> <tasks:prompt>Testing Thingy</tasks:prompt> <tasks:type>string</tasks:type> </tasks:param> </tasks:paramgroup> </tasks:postinstallscript> |
Note that the only type recognized at this stage is "string" but others will follow. A more complex example follows:
<tasks:postinstallscript> <tasks:paramgroup> <tasks:id>first</tasks:id> <tasks:instructions>The first group of questions relates primarily to your favorite color. Answer wisely. </tasks:instructions> <tasks:param> <tasks:name>test</tasks:name> <tasks:prompt>Testing Thingy</tasks:prompt> <tasks:type>string</tasks:type> <tasks:default>hi</tasks:default> </tasks:param> <tasks:param> <tasks:name>test2</tasks:name> <tasks:prompt>Testing Thingy 2</tasks:prompt> <tasks:type>string</tasks:type> </tasks:param> </tasks:paramgroup> <tasks:paramgroup> <tasks:id>second</tasks:id> <tasks:name>first::test</tasks:name> <tasks:conditiontype>preg_match</tasks:conditiontype> <tasks:value>g+</tasks:value> <tasks:param> <tasks:name>test</tasks:name> <tasks:prompt>Testing Thingy a</tasks:prompt> <tasks:type>string</tasks:type> <tasks:default>hi</tasks:default> </tasks:param> <tasks:param> <tasks:name>test2</tasks:name> <tasks:prompt>Testing Thingy b</tasks:prompt> <tasks:type>string</tasks:type> </tasks:param> </tasks:paramgroup> </tasks:postinstallscript> |
This post-installation script has two parameter groups. The first parameter group has special instructions that are displayed to the user to assist in answering the required prompts. After the first group is processed, the second group is processed (naturally). However, in this case, the second group is a conditional parameter group. A conditional parameter group examines the user input from previous parameter groups and only displays its parameter prompts if a single parameter fits a test. The condition is defined by three tags, <tasks:name>, <tasks:conditiontype>, and <tasks:value>. Note that all three tags are required or xml validation will fail.
<tasks:name> is the parameter name from a previous parameter group. The format of name is groupID::parameterName, so as you see above, "first::test" refers to the <tasks:param> test from the <tasks:paramgroup> first.
<tasks:conditiontype> determines how the parameter input function will process the value of the parameter specified in <tasks:name>, and can be one of three values, "=" "!=" or "preg_match".
=: This (obviously) tests whether the parameters value is equal to the <tasks:value> tag
!=: This (obviously) tests whether the parameters value is not equal to the <tasks:value> tag
preg_match: This uses the content of the <tasks:value> tag as if it were the stuff between / and / in a preg_match() function call. Do NOT include // brackets in the regular expression. In the <tasks:paramgroup> second, the value "g+" will become:
<?php
preg_match('/g+/', first::test value)
?> |