Install scripts in a site package #

This page is for developers who write or change the PHP part of a site package. It answers: how the scripts are declared, which functions the installer calls, in which order, with what, and what they must give back.

Contents #

1. Declaring the scripts
2. The hook functions
3. The order inside Create sites
4. What the functions receive
5. What the functions return
6. The installer class pattern
7. Rules and pitfalls
8. Related pages

Declaring the scripts #

The scripts are PHP files in the package's settings/ directory, each listed in package.xml:

<settings>
  <settings-file filename='ini-site.php'/>
  <settings-file filename='ini-admin.php'/>
  <settings-file filename='ini-common.php'/>
  <settings-file filename='sevenx-multi-site-installer.php'/>
  <settings-file filename='install-scripts.php'/>
  <settings-file filename='roles.php'/>
  <settings-file filename='preferences.php'/>
</settings>

The Create sites step includes every listed file that exists, with include_once, from <package path>/settings/<filename> (kernel/setup/steps/ezstep_create_sites.php). A file that is in settings/ but not listed is not included by the step; it can still be loaded by a listed file (the 7x installer loads post-install-fix.php with require_once).

The hook functions #

The scripts define plain PHP functions with fixed names. The step calls each one only when it exists (function_exists()):

The names are kernel identifiers kept from the original product and are not renamed.

The order inside Create sites #

1. Fetch the site package (EZSW-041 when it cannot be fetched).
2. Include the listed scripts, call eZSitePreInstall().
3. Create the languages, then install the required packages in order (see Dependencies and install order).
4. Build $parameters and call eZSiteINISettings(), eZSiteAdminINISettings(), eZSiteCommonINISettings(); write the results.
5. Call eZSiteRoles() and create the roles; call eZSitePreferences() and set the preferences.
6. Call eZSitePostInstall() with the content's language as the default language.
7. Make the editor siteaccess, and the Admin UI siteaccess when exp_adminui is present.
8. Call eZSiteFinalText().

What the functions receive #

$parameters is built just before the INI hooks. Its keys include:

What the functions return #

The INI hooks return a list of entries, each for one INI file:

return array(
    array( 'name' => 'site.ini',
           'reset_arrays' => true,
           'settings' => array( 'SiteSettings' => array( 'SiteName' => 'My site' ) ) ),
);

The public and admin entries are saved as .append.php files in settings/siteaccess/<name>/, the common ones in settings/override/. An entry that is false is skipped.

eZSiteRoles() returns entries with name, optional policies (each module, function, optional limitation) and optional assignments (each user_id, optional limitation with identifier and value). eZSitePreferences() returns entries with user_id and preferences (each name and value); a failed one is reported as EZSW-070.

The installer class pattern #

The 7x and CJW packages keep the logic in one class and let each hook file only create it:

// install-scripts.php of sevenx_multisite
function eZSitePreInstall( )
{
    $installer = new sevenxMultiSiteInstaller( array( 'var_dir' => 'var/site' ) );
    $installer->preInstall();
}

function eZSitePostInstall( &$parameters )
{
    $installer = new sevenxMultiSiteInstaller( $parameters );
    $installer->postInstall();
}

sevenxMultiSiteInstaller extends the kernel's eZSiteInstaller (kernel/classes/ezsiteinstaller.php). eZSiteInstaller::postInstall() runs the list of steps from postInstallSteps() one by one (executeSteps()). When a step aborts, eZSiteInstaller::abortedStep() keeps it, and Create sites stops with EZSW-080: "The post-install of site package '...' stopped at step N of M (...): the steps after it did not run". What the 7x installer does step by step is described in The multisite installer script; the CJW one in The installer scripts.

Rules and pitfalls #

• One site package per run. The hooks are global functions, included once; only the chosen site package's scripts are included.
• Settings are not stored back. eZPackage reads <settings> but does not write it; keep the list in the source repository (see package.xml reference).
• The language during the post-install is the language the bundled content is in, not the primary language chosen; the step switches back afterwards.
• No secrets in scripts. The scripts are published in the archive on the package server.
• Test with every front end. The wizard, the kickstarter and exp:install all run the same Create sites step, so one test run covers the code path; test with a dry run first (see How the kickstarter and the console use packages).

Related pages #

• Site package basics
• Site packages: start here
• Changing the installer script
• Choosing an install method, 4.3 Site packages
• The setup wizard, 5.3.15 Creating sites
• Contribute your site package: 7x and the Exponential Foundation strongly encourage you to submit your site package by pull request.
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.