This HowTo explains the basics of creating and using plugins for the installer.

Plugins are used during the install, uninstall and upgrade of packages. When installing a package, the following process order is performed:

file copy => config plugins => process plugins

1. Creating a plugin

First of all, you have to decide where your plugin should "plug" in ;) Currently this can be at configuration screen (for showing some input forms) or after configuration screen (so its a processing plugin).

A plugin consists of at least one file named after the event which triggers the plugin. This can be config.php for config plugins, or exec.php for processing plugins. If the exec plugin should be executed within a special install mode (e.g. "install", "uninstall", "change_config") name it exec_install.php, exec_uninstall.php or exec_change_config.php.

The code in the scripts is functional. Just write the php code you want the installer to perform. In config mode, all plugin output is directly passed on to output form shown when configuring new installed packages.

In each of the plugin files, you have several standard variables via the $GLOBALS['ZI_*'] global variables. For a detailed discussion, consult this list of variables.

Finally you have to create a package containing your plugin. To tell the installer to register a new plugin, you have to define the corresponding entries in the package.xml:

<package version="1.0"
        xmlns="http://www.zzoss.com/NS/installer/package/">
  ... cut ...
  <release>
    ... cut ...
    <plugin>
      <filelist>
        <file baseinstalldir="com.zzoss.installer.plugin.sample/" name="config.php"/>
        <file baseinstalldir="com.zzoss.installer.plugin.sample/" name="exec_change_config.php"/>
        <file baseinstalldir="com.zzoss.installer.plugin.sample/" name="exec_install.php"/>
        <file baseinstalldir="com.zzoss.installer.plugin.sample/" name="exec_uninstall.php"/>
      </filelist>
    </plugin>
    ... cut ...
  </release>
</package>

2. Using a plugin in own packages

Currently it's only possible to supply a directory to a plugin as input source. Let's say your package com.zzoss.sample is finished and you have written a plugin which needs some .dat files as input, so you would have a file structure like this:

/com.zzoss.sample/ (package root)
  com.zzoss.installer.my_plugin/
    data1.dat
  my_script1.php
  my_script2.php
  package.xml

Now you have to tell the installer to use the com.zzoss.installer.my_plugin by adding following entries to the package.xml:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0"
        xmlns="http://www.zzoss.com/NS/installer/package/">
  <name>com.zzoss.sample</name>
  <summary>ZZ/OSS Sample Package</summary>
  <description>This is just a sample package.</description>
  --- cut ---
  <release>
    <version>0.1</version>
    <date>2003-01-01</date>
    <license url="http://www.gnu.org/licenses/gpl.txt" version="2">GPL</license>
    <state>beta</state>
    <notes>Initial framework package.</notes>
    --- cut ---
    <builds>
        <build dir="com.zzoss.installer.my_plugin/" plugin="com.zzoss.installer.my_plugin" rel="ge" version="0.1" />
    </builds>
  </release>
</package>

The required version of the plugin is defined in version-attribute, the relation to it is defined in rel-attribute (ge (greater-or-equal) or eq (equal)).

-- ChristianZonsius