Custom install scripts

A package installed through the administration can bring install steps of its own: a PHP class that adds pages to the install wizard and does extra work, for example asking for a setting and storing it. Such a step is an item of the type ezinstallscript in the package's <install> list.

Example: an extra step for a package

The package products is in var/storage/packages/local/products/. Add the step in four parts.

1. The item. Add it at the place in the list where the step should run, usually at the end of <install> in package.xml:

<item type="ezinstallscript" filename="myinstallscript" sub-directory="post-install"/>

2. The description, post-install/myinstallscript.xml. It names the PHP file and its class; the description is shown in the list of items to install:

<?xml version="1.0" encoding="UTF-8"?>
<install-script filename="myinstallscript.php"
                classname="myInstallScript"
                description="This is my custom install step" />

3. The template of the step, post-install/templates/myownstep.tpl:

<form method="post" action={'package/install'|ezurl}>
    {include uri="design:package/install/error.tpl"}
    {include uri="design:package/install_header.tpl"}
    <p>This is my custom step.</p>
    <label><input type="checkbox" name="MyCheckBox" /> Tick if you like</label>
    {include uri="design:package/navigator.tpl"}
</form>

The form token is added to the form by the form token extension; the step needs nothing for it.

4. The class, post-install/myinstallscript.php. It extends eZInstallScriptPackageInstaller and passes its steps to the constructor of eZPackageInstallationHandler. Each step has an ID, a name, a template and up to three methods: initialize (before the step is shown, to set template variables), validate (after the form is posted; false shows the step again) and commit (after it validated).

<?php
class myInstallScript extends eZInstallScriptPackageInstaller
{
    public function __construct( $package, $type, $installItem, $name = null, $steps = null )
    {
        $steps = array();
        $steps[] = array( 'id' => 'my_own_step',
                          'name' => 'My own step',
                          'methods' => array( 'initialize' => 'initializeMyOwnStep',
                                              'validate' => 'validateMyOwnStep',
                                              'commit' => 'commitMyOwnStep' ),
                          'template' => 'myownstep.tpl' );
        eZPackageInstallationHandler::__construct( $package, $type, $installItem,
                                                   'My own custom step', $steps );
    }

    function initializeMyOwnStep( $package, $http, $step, &$persistentData, $tpl, $module )
    {
        return true;
    }

    function validateMyOwnStep( $package, $http, $currentStepID, &$stepMap, &$persistentData, &$errorList )
    {
        $persistentData['my_checkbox'] = $http->hasPostVariable( 'MyCheckBox' );
        return true;
    }

    function commitMyOwnStep( $package, $http, $step, &$persistentData, $tpl )
    {
        eZDebug::writeNotice( 'Checkbox: ' . ( $persistentData['my_checkbox'] ? 'on' : 'off' ), __METHOD__ );
        return true;
    }
}

The kernel reads the description, includes the PHP file named there and creates the class with new myInstallScript( $package, $type, $installItem ). The step's template is looked up in the templates directory next to the description.

Notes for code from older releases

Install scripts written for the 4.x releases named their constructor after the class (function myInstallScript(...)) and called the parent method eZPackageInstallationHandler(). PHP 8 no longer treats such a method as a constructor: rename it to __construct and call the parent constructor as shown. Objects are no longer passed by reference (&$package); keep the reference only on $persistentData, $stepMap and $errorList, which the step changes.

More

• package.xml format and Installing packages.
• The code: ezpackageinstallationhandler.php in kernel/classes/, and ezinstallscript/ in kernel/classes/packageinstallers/.