Difference between revisions of "Extension Installer/Installer Hooks"

From Joomla! Documentation

< Extension Installer
(New page: Some extension installers offer installer hooks for the installing application, such as the component installer. This system replaces the older 'com_install' and 'com_uninstall' methods th...)
 
(Updated with information shared by Sam Moffat on the developer's mailing list)
Line 1: Line 1:
 
Some extension installers offer installer hooks for the installing application, such as the component installer. This system replaces the older 'com_install' and 'com_uninstall' methods that used to exist instead using an object to contain this information.
 
Some extension installers offer installer hooks for the installing application, such as the component installer. This system replaces the older 'com_install' and 'com_uninstall' methods that used to exist instead using an object to contain this information.
  
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 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
 
* install
 
* uninstall
 
* uninstall
 
* update
 
* update
 
* discover_install
 
* discover_install
* preflight
 
 
* postflight
 
* 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 that is used when the extension is 'discovered'. Finally preflight and postflight accepts a param display what sort of operation we're doing (one of the above options: install, uninstall, update, discover_install) and is triggered before different operations take place.
 
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 that is used when the extension is 'discovered'. Finally preflight and postflight accepts a param display what sort of operation we're doing (one of the above options: install, uninstall, update, discover_install) and is triggered before different 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 install to literally see the execution order of these hooks. Other components, like 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 ==
 +
 +
Effectively preflight runs as soon as possible after we've got the manifest file, 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) and 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 effectively where com_install ran which 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 run when a component has all of 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 components. Naturally, 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 that 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 of this).

Revision as of 04:50, 19 July 2011

Some extension installers offer installer hooks for the installing application, such as the component installer. This system replaces the older 'com_install' and 'com_uninstall' methods that used to exist instead using an object to contain this information.

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 that is used when the extension is 'discovered'. Finally preflight and postflight accepts a param display what sort of operation we're doing (one of the above options: install, uninstall, update, discover_install) and is triggered before different 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 install to literally see the execution order of these hooks. Other components, like 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[edit]

Effectively preflight runs as soon as possible after we've got the manifest file, 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) and 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[edit]

The install/update hooks run effectively where com_install ran which 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 run when a component has all of 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 components. Naturally, the uninstall hook runs when the extension is being uninstalled.

The postflight hook[edit]

Postflight, at least for components, runs after the #__extensions entry has been made/updated (install/update) and that 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 of this).