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 "replace", "windowseol", and "unixeol". The complex task is "postinstallscript". "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. "windowseol" and "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. "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-version 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> <paramgroup> <id>first</id> <param> <name>test</name> <prompt>Testing Thingy</prompt> <type>string</type> </param> </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> <paramgroup> <id>first</id> <param> <name>test</name> <prompt>Testing Thingy</prompt> <type>string</type> <default>hi</default> </param> <param> <name>test2</name> <prompt>Testing Thingy 2</prompt> <type>string</type> </param> </paramgroup> <paramgroup> <id>second</id> <name>first::test</name> <conditiontype>preg_match</conditiontype> <value>g+</value> <param> <name>test</name> <prompt>Testing Thingy a</prompt> <type>string</type> <default>hi</default> </param> <param> <name>test2</name> <prompt>Testing Thingy b</prompt> <type>string</type> </param> </paramgroup> </tasks:postinstallscript> |
This post-installation script has two parameter groups. 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, <name>, <conditiontype>, and <value>. Note that all three tags are required or xml validation will fail.
<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 <param> first from the <paramgroup> test.
<conditiontype> determines how the parameter input function will process the value of the parameter specified in <name>, and can be one of three values, "=" "!=" or "preg_match".
=: This (obviously) tests whether the parameters value is equal to the <value> tag
!=: This (obviously) tests whether the parameters value is not equal to the <value> tag
preg_match: This uses the content of the <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 <paramgroup> second, the value "g+" will become:
<?php
preg_match('/g+/', first::test value)
?> |
| Пред. | Начало | След. |
| <file> | Уровень выше | <compatible> |