Managing Component Updates (Script.php)
From Joomla! Documentation
Revision as of 12:48, 27 May 2011 by Sm990
This file contains the component-specific methods preflight, install, update, postflight and uninstall. This file is where the component developer implements all of the unique code for these actions. For this example, in addition to various checks, HTML is inserted into the back-end output to show which code has been executed. You may choose to display different HTML, or to display none for your component.
preflight( $type, $parent )
This is where most of the checking should be done before install, update or discover_install. Preflight is executed prior to any Joomla install, update or discover_install actions. Preflight is not executed on uninstall. A string denoting the type of action (install, update or discover_install) is passed to preflight in the $type operand. Your code can use this string to execute different checks and responses for the three cases. It is appropriate to check the Joomla version and the existing component version in the preflight module. A failure of either of these two should cause an abort of the action. An abort is triggered by returning a false value from this preflight method. On receiving a false return value, Joomla will reverse any actions already completed. The PHP function version_compare is useful to compare version strings. Joomla also uses version_compare to define the sequence of SQL file execution, when an update is being executed that spans multiple versions. In this example, the preflight method checks that Joomla version 1.6 or greater is in use. If an earlier version is in use, the install or update will abort. Since this script.php file only works in Joomla version 1.6 or greater, this check is currently not very useful. As subsequent Joomla versions become available, this check will be useful. Try changing the version in the script.php file to '1.7'. Installs and updates should fail if you are using a Joomla release prior to 1.7. In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed.
install( $parent )
Install is executed after the Joomla install database scripts have completed. Returning 'false' will abort the install and undo any changes already made. It is cleaner to abort the install during preflight, if possible. Since fewer install actions have occurred at preflight, there is less risk that that their reversal may be done incorrectly.
update( $parent )
Update is executed after the Joomla update database scripts have completed. Returning 'false' will abort the update and undo any changes already made. It is cleaner to abort the update during preflight, if possible. Since fewer update actions have occurred at preflight, there is less risk that that their reversal may be done incorrectly.
postflight( $type, $parent )
Postflight is executed after the Joomla install, update or discover_update actions have completed. It is not executed after uninstall. Postflight is executed after the extension is registered in the database. The type of action (install, update or discover_install) is passed to postflight in the $type operand. Postflight cannot cause an abort of the Joomla install, update or discover_install action. The postflight method is a good place to set the default values of component parameters during initial installs. Postflight can be used for any other action needed that follows the install, update or discover_install actions.
uninstall( $parent )
The uninstall method is executed before any Joomla uninstall action, such as file removal or database changes. Uninstall cannot cause an abort of the Joomla uninstall action.