Path / documentation / ez publish / technical manual / 5.x / features / packages / custom install scripts

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Custom install scripts

Packages that can be installed via the administration interface may include specific custom install and uninstall scripts. A custom script can be called at any stage during the package installation/uninstallation process. These scripts can be interactive and are capable of displaying extra wizard steps. Interactive scripts are based on a "wizard step" mechanism provided by the class "eZPackageInstallationHandler".

The following example demonstrates how to implement a custom install script for a package.


Let's say that you need to add some additional post-install step(s) to a content object package called "Products" which is located under the "ez_systems" internal repository (in the "var/storage/packages/ez_systems/products" directory). To implement a post-install interactive script for this package, do the following:

  1.  Create the following new sub-directories in the package directory:
    • post-install
    • post-install/templates
  2.  Open the "package.xml" file located in the package directory and edit it. Find the list of items to install which is specified between the <install> and </install> XML tags and add the following item in the end of this list:
    <item type="ezinstallscript"
          sub-directory="post-install" />
  3. Create a file called "myinstallscript.xml" in the "post-install" directory (this file must contain a description of your install script) and add the following lines to it:

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

    This will tell the system that additional install step(s) is implemented in a PHP class called "myInstallScript" located in the "post-install/myinstallscript.php" file. The text description of the install script will be displayed in the beginning of the package installation process (as shown in the following screenshot).

    Installing Custom Package

    Installing Custom Package

  4. Create a file called "myownstep.tpl" in the "post-install/templates" directory (this file will contain a template for the additional install step implemented by your install script) and add the following lines to it:

    <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>You may even click the checkbox if you want</label>
        <div class="block">
          <input class="button" type="checkbox" name="MyCheckBox" />
        {include uri="design:package/navigator.tpl"}

    The last step of the package installation will be displayed according to this template (look at the next screenshot).

    Package Custom Step

    Package Custom Step

  5.  Create a new file called "myinstallscript.php" in the "post-install" directory. This file must contain a PHP class called "myInstallScript" where all the steps are implemented (according to the description given in the "post-install/myinstallscript.xml" file). Add the following lines to the "myinstallscript.php" file:
    class myInstallScript extends eZInstallScriptPackageInstaller
      function myInstallScript( &$package, $type, $installItem )
            eZDebug::writeDebug( $installItem, "Hello from myInstallScript" );
            $steps = array();
            $steps[] = array(
              'id' => 'my_own_step',
              'name' => 'My own step',
              'methods' => array( 'initialize' => 'initializeMyOwnStep',
                   'validate' => 'validateMyOwnStep',
                   'commit' => 'commitMyOwnStep' ),
              'template' => 'myownstep.tpl' );
            $this->eZPackageInstallationHandler( $package,
                                                 'My own custom step',
                                                 $steps );
      // Function that is called before the step is displayed.
      // You can use it to set variables for your template.
      function initializeMyOwnStep( &$package, &$http, $step, &$persistentData, &$tpl, &$module )
            eZDebug::writeDebug( "Hello from initializeMyOwnStep()" );
            return true;
      // This function is called after user has submitted the form.
      // If this function returns "false", the step will be
      // displayed again.
      function validateMyOwnStep( &$package, &$http, $currentStepID, &$stepMap, &$persistentData, &$errorList )
            eZDebug::writeDebug( "Hello from validateMyOwnStep()" );
            return true;
      // This function is called after the form is submitted
      // and validated.
      function commitMyOwnStep( &$package, &$http, $step, &$persistentData, &$tpl )
            eZDebug::writeDebug( "Hello from commitMyOwnStep()" );
            return true;

Svitlana Shatokhina (14/09/2010 12:17 pm)

Andrea Melo (27/12/2012 3:48 pm)

Geir Arne Waaler, Andrea Melo


There are no comments.