Joomla! Documentation™

Some extension installers offer installer hooks for the application, such as the component installer. This system replaces the older com_install and com_uninstall methods.

The class name of the item should be the element name followed by InstallerScript. So for com_alpha the class name would be com_alphaInstallerScript. The hooks, in order of execution, are:

• preflight
• install
• uninstall
• update
• discover_install
• postflight

Install and uninstall are analogous to to the old com_install and com_uninstall functions. Update is a new function handled for update situations and discover_install is a special version of install used when the extension is 'discovered'. Finally preflight and postflight accept a param to display the sort of operation performed. (One of the above options: install, uninstall, update, discover_install) and is triggered before those operations take place.

You can find practical examples on using the installation script files and hooks inside the tests/_data/installer_packages directory of Joomla!'s SVN repository. It's advisable to study com_alpha and try to install it on a Joomla! 1.6/1.7 instance to see the execution order of these hooks. Other components, such as com_beta showcase other use cases of the installer scripts. For instance, com_beta shows you how to abort the extension installation.

The preflight Hook

Preflight runs as soon as possible after we've got the manifest file and worked out if we need to switch into an update mode from the install. (E.g. if the extension is installed then the system transparently swaps into the update mode out of install so that the installation hooks work properly.) It has worked out where the script file is and loaded it. At this point you could conceivably prevent the installation by calling the abort mechanism from the parent or prepare anything ahead of the file copy and database changes occurring. It is one of the new hooks in 1.6 to let you get your own code in as close to the installer process kicking off as the developers felt safe. You're also handed a copy of the installer object (from memory) and a param to say if the preflight is for install or update so that if there is a difference you can handle that.

The install/update/discover_install/uninstall Hooks

The install/update hooks run where com_install ran that was after the files have been copied (except the manifest) and the database has been updated (except for the #__extensions or equivalent entry).

The install hook runs only when a component is being installed, i.e. it wasn't already installed. The update hook runs when the component is being updated, i.e. when it was already installed. The discover_install hook runs when a component has all its files copied manually and the user is using the Discover feature of extensions manager to install it, i.e. let Joomla! update its database so that it "knows" about this component. The uninstall hook runs when the extension is being uninstalled.

The postflight Hook

Postflight, at least for components, runs after the #__extensions entry has been made/updated (install/update) and the manifest file has been copied. At this point there should be no reason for the extension to fail. For those extensions utilising a redirect that broke with the shift from 1.5 to 1.6, where 1.5 com_installer doesn't do a redirect after install and now 1.6 com_installer does, you can instruct the installer in postflight to redirect to a custom extension installation screen from a component. (See com_alpha's scriptfile for an example.)