Post-install Scripts in PEAR 1.4.0

First, the fun stuff.

To understand this post, you need to have a basic understanding of how PEAR works. PEAR is structured around re-distributable archives of PHP files called "packages." A package is defined by a simple file that describes the contents of a package. This file is always called package.xml, and describes the authors, the nature of the package, and the list of files in the package.

Post-install scripts are implemented in package.xml as a task. Tasks were implemented in a rudimentary and undocumented manner in older versions of PEAR with the "replace" tag:

[xml]<file role="php" name="blah.php">
<replace from="@something@" to="version" type="package-info"/>
</file>[/xml]

the PEAR installer would look through the blah.php file and do a simple str_replace('@something@', XXX, contents of blah.php); where XXX is the package version.

In package.xml 2.0, namespace <strong>http://pear.php.net/dtd/package-2.0</strong>, tasks are implemented as namespace <strong>http://pear.php.net/dtd/tasks-1.0</strong>. Therefore, our replace task now looks like:

[xml]<file role="php" name="blah.php">
<tasks:replace from="@something@" to="version" type="package-info"/>
</file>[/xml]
Post-install scripts are implemented as php files that contain the postinstallscript task. The following is a post-install script:

[xml]<file role="php" name="blah.php">
<tasks:postinstallscript/>
</file>[/xml]

The following is invalid and will trigger a validation error, as only php files may be post-install scripts:

[xml]<file role="data" name="blah.php">
<tasks:postinstallscript/>
</file>[/xml]

The internal structure of blah.php is also very specific. It must contain a single class named "path_to_file_postinstall" so that our example blah.php must contain:

If blah.php were located in a subdirectory, such as foo, the class would be named foo_blah_postinstall. In addition, a basic post-install script MUST contain the methods init() and run() as shown above. The script you see there is the simplest post-installation script that will succeed.

A post-install script is most useful when it can process user input to do setup. PEAR supports three different frontends for installation, the Command-Line Interface (CLI), Web Interface, and GTK Interface. Retrieving input is completely different for all three interfaces. To simplify implementation of this, the parameters must be specified in the package.xml file, and the PEAR Frontend will be responsible for prompting the user and retrieving input. Fortunately, there are a large number of options available for customizing parameters that both simplify validation and eliminate common errors.

Parameters are grouped using a <paramgroup> tag. Each paramgroup has a mandatory id that may only contain letters and numbers, and then a mandatory list of parameters. Here is the simplest <paramgroup> tag possible:

[xml] <paramgroup>
<id>first</id>
<param>
<name>test</name>
<prompt>Testing Thingy</prompt>
<type>string</type>
</param>
</paramgroup>[/xml]

Note that the only type recognized at this stage is "string" but others will follow. A more complex example follows:

[xml] <file baseinstalldir="/" name="sub2.php" role="php">
<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>
</file>[/xml]

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:
  <?php preg_match('/g+/', first::test value) ?>

After processing each paramgroup, the frontend post-install script handler calls the "run()" method of a post-install script. In this example script:

[xml] <file baseinstalldir="/" name="sub2.php" role="php">
<tasks:postinstallscript>
<paramgroup>
<id>first</id>
<param>
<name>user</name>
<prompt>Database Username</prompt>
<type>string</type>
<default>hi</default>
</param>
<param>
<name>pass</name>
<prompt>Database Password</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>
</file>[/xml]

You can see a realistic example of the way an install script might work. Note that all output is displayed using the outputData() method of PEAR_Frontend. Anything else could corrupt the display in frontends other than the CLI frontend, rendering your package's install script useless for annoyed patrons of the Web and Gtk frontends.

First, the user is prompted for their database username/password. After both are filled in (the Frontend will not advance until all parameters are filled in, no blank parameters are allowed), the input is passed to the run() method. In this example, the input will be something like this:

The final parameter, $installtype, can be either install or upgrade.(No longer true)

If the user cancels processing of the install script, or there is any error, the script will be called with:

The first element contains an associative array listing the paramgroups that were successfully processed and executed. In this way, the installation script can clean up any system changes on error in an incremental way.

Security Issues

Obviously, allowing unknown scripts to run at install-time is an inherent security risk, particularly on shared hosts where admins are likely to run "pear upgrade-all"

Because of this, several steps need to be implemented to make install scripts safe. First, the restrictions that I would assume:

1. Single users are the only people who really need install scripts
2. It should be possible to run installation scripts after installation is over, perhaps with "pear run-scripts Packagename"

With these restrictions, it should be possible to make installations secure. Necessary steps would be to add a configuration variable "run_installscripts" which would default to 0 (off). When a package is installed that has installation scripts, the user would be notified to run them, and how to do it.

This should kill off the possibility of malicious post-install scripts, while keeping full flexibility. Any other evil scenarios that you can think of should be mentioned now, so I can add in safeguards.

In conclusion, it's been a long time in coming, but PEAR is finally reaching a level of maturity that matches or exceeds the most flexible and robust installation systems out there.