Joomla! Documentation - User contributions [en]

Archived:Managing Component Updates (Manifest file)

2012-09-29T22:12:41Z

Sm990: /* The entire manifest file */

{{version/tutor|1.6,1.7,2.5}}{{Chunk:Managing Component Updates - Contents}}{{review}}

== Manifest File (democompupdate.xml) ==
The manifest file in this example is very similar to that of normal components. Important contents for this example include:

=== sql folder ===
Note the inclusion of the SQL folder in the administration files section. This tells Joomla to copy the contents of this folder to the web site during install or update. The ''schemapath'' declaration below depends on Joomla copying these files during the install or update process.

<source lang="xml">
<administration>
<files folder="admin">
<folder>sql</folder>
</files>
</administration>
</source>

=== name ===
This is the name of the component. The 'getParam($key)' method in the ''script.php'' file uses this value to identify the correct row in the extensions table. The ''manifest_cache'' field in the ''extensions'' table has the version string for the currently installed component.

<source lang="xml">
<name>COM_DEMOCOMPUPDATE</name>
</source>

=== version ===
Joomla stores this value in the ''manifest_cache'' field of the ''extensions'' table. The ''extensions'' table is where the custom code in the ''script.php'' file reads the version string of the currently installed component, and compares it to the version string of the update.

The custom component code uses this comparison to abort an update if the version sequence is not allowed. Joomla also compares this string to the SQL update file names, to determine which SQL commands to execute.

<source lang="xml">
<version>1.0</version>
</source>

=== Joomla version ===
The component developer records in the manifest file the version of Joomla that is required to run the component.
<source lang="xml">
<extension type="component" version="1.6" method="new">
</source>

Your component installation script.php file can use this value to control whether a component installation or update should be allowed or not allowed.

=== schemapath ===
This defines the directory that contains SQL files for component incremental database updates.
You may choose to put the SQL files somewhere else in your component release, but make sure their location is documented here.

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates</schemapath>
</schemas>
</update>
</source>

=== #__schemas table ===
The SQL files have a second function.
In addition to potentially modifying the MySQL database, Joomla uses the names of these SQL files to enable updates to the ''version_id'' field in the ''#__schemas'' table for your component.
It is important to have an SQL file for EVERY version of your component.
The file should be empty if you have no SQL code to execute when updating to that version.
You must have a file or the ''version_id'' will not get updated correctly.
Joomla uses the ''version_id'' in the ''#__schemas'' table as the ''from'' version when calculating updates ''from'' an older version ''to'' a new version.

It is important to include these ''schemapath'' lines in your manifest file, even if you have no SQL commands to execute.
By including these lines and including empty SQL files, the ''version_id'' value will be correctly maintained in the ''#__schemas'' table.

If your new component version is not executing the SQL file as expected, check the ''#__schemas'' table to see if the previous version was correctly recorded.
If it is not, then your update will not execute the SQL file when updating from that version to a newer version.

== The entire manifest file ==
Here is the entire manifest file for democompupdate version 1.0.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6" method="new">
<name>COM_DEMOCOMPUPDATE</name>
<creationDate>2011 05 11</creationDate>
<author>Your Name Here</author>
<copyright>Free to copy</copyright>
<license>none</license>
<version>1.0</version>
<description>Test the Install and Update Process</description>

<scriptfile>script.php</scriptfile>
<install>
<sql>
<file driver="mysql" charset="utf8">sql/install_data.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates</schemapath>
</schemas>
</update>
<files folder="site">
<filename>democompupdate.php</filename>
<filename>controller.php</filename>
<folder>models</folder>
<folder>views</folder>
</files>
<administration>
<files folder="admin">
<folder>sql</folder>
</files>
</administration>
</extension>
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Component Development]]

Archived:Managing Component Updates (Manifest file)

2012-09-29T22:12:06Z

Sm990: /* #__schemas table */

{{version/tutor|1.6,1.7,2.5}}{{Chunk:Managing Component Updates - Contents}}{{review}}

== Manifest File (democompupdate.xml) ==
The manifest file in this example is very similar to that of normal components. Important contents for this example include:

=== sql folder ===
Note the inclusion of the SQL folder in the administration files section. This tells Joomla to copy the contents of this folder to the web site during install or update. The ''schemapath'' declaration below depends on Joomla copying these files during the install or update process.

<source lang="xml">
<administration>
<files folder="admin">
<folder>sql</folder>
</files>
</administration>
</source>

=== name ===
This is the name of the component. The 'getParam($key)' method in the ''script.php'' file uses this value to identify the correct row in the extensions table. The ''manifest_cache'' field in the ''extensions'' table has the version string for the currently installed component.

<source lang="xml">
<name>COM_DEMOCOMPUPDATE</name>
</source>

=== version ===
Joomla stores this value in the ''manifest_cache'' field of the ''extensions'' table. The ''extensions'' table is where the custom code in the ''script.php'' file reads the version string of the currently installed component, and compares it to the version string of the update.

The custom component code uses this comparison to abort an update if the version sequence is not allowed. Joomla also compares this string to the SQL update file names, to determine which SQL commands to execute.

<source lang="xml">
<version>1.0</version>
</source>

=== Joomla version ===
The component developer records in the manifest file the version of Joomla that is required to run the component.
<source lang="xml">
<extension type="component" version="1.6" method="new">
</source>

Your component installation script.php file can use this value to control whether a component installation or update should be allowed or not allowed.

=== schemapath ===
This defines the directory that contains SQL files for component incremental database updates.
You may choose to put the SQL files somewhere else in your component release, but make sure their location is documented here.

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates</schemapath>
</schemas>
</update>
</source>

=== #__schemas table ===
The SQL files have a second function.
In addition to potentially modifying the MySQL database, Joomla uses the names of these SQL files to enable updates to the ''version_id'' field in the ''#__schemas'' table for your component.
It is important to have an SQL file for EVERY version of your component.
The file should be empty if you have no SQL code to execute when updating to that version.
You must have a file or the ''version_id'' will not get updated correctly.
Joomla uses the ''version_id'' in the ''#__schemas'' table as the ''from'' version when calculating updates ''from'' an older version ''to'' a new version.

It is important to include these ''schemapath'' lines in your manifest file, even if you have no SQL commands to execute.
By including these lines and including empty SQL files, the ''version_id'' value will be correctly maintained in the ''#__schemas'' table.

If your new component version is not executing the SQL file as expected, check the ''#__schemas'' table to see if the previous version was correctly recorded.
If it is not, then your update will not execute the SQL file when updating from that version to a newer version.

== The entire manifest file ==
Here is the entire manifest file for version 1.0.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6" method="new">
<name>COM_DEMOCOMPUPDATE</name>
<creationDate>2011 05 11</creationDate>
<author>Your Name Here</author>
<copyright>Free to copy</copyright>
<license>none</license>
<version>1.0</version>
<description>Test the Install and Update Process</description>

<scriptfile>script.php</scriptfile>
<install>
<sql>
<file driver="mysql" charset="utf8">sql/install_data.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates</schemapath>
</schemas>
</update>
<files folder="site">
<filename>democompupdate.php</filename>
<filename>controller.php</filename>
<folder>models</folder>
<folder>views</folder>
</files>
<administration>
<files folder="admin">
<folder>sql</folder>
</files>
</administration>
</extension>
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Component Development]]

Archived:Managing Component Updates (Update SQL files)

2012-09-09T21:27:56Z

Sm990: /* Update SQL files */

Archived:Managing Component Updates (How to use this example)

2012-07-01T02:06:54Z

Sm990: /* Summary */

Archived:Managing Component Updates (Script.php)

2012-07-01T01:56:33Z

Sm990: /* Script.php */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 and several component parameters are created and maintained. You may choose to display different HTML, or to display none for your component.

=== preflight ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file. It is the same for all versions of com_democompupdate.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Portal:Component Development

2012-07-01T01:43:37Z

Sm990: /* Other component topics */

__NOTOC__
== Recommended Reading ==
=== General ===
* [[Joomla Beginning Developer Course]]
* [[Setting up your workstation for Joomla! development]]
* [[Secure coding guidelines]]
=== Specific ===
<onlyinclude>
====Developing a Model-View-Controller (MVC) Component {{JVer|1.5}}====
* [[Developing a Model-View-Controller Component - Part 1]]
* [[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]
* [[Developing a Model-View-Controller Component - Part 3 - Using the Database]]
* [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]
* [[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]
* [[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

====Developing a Model-View-Controller (MVC) Component {{JVer|1.6}}====
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6|Introduction]]
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

====Other component topics====
* [[File Structure and Naming Conventions]]
* [[Component Program Flow]]. UML sequence diagrams showing the control flow for a component. {{JVer|1.5}}
* [[Component parameters]]
* [[Components:xml installfile]]. An example component XML installation file. {{JVer|1.5}}
* [[Manifest files]] for the installation of extensions {{JVer|1.6}}
* [[Supporting SEF URLs in your component]]
* [[Supporting plugins in your component]]
* [[Using JPagination in your component]]
* [[Adding sortable columns to a table in a component]]
* [[How to use the JPane classes in a component]] {{JVer|1.5}}
* [[How to use the JHtmlTabs in a component]]
* [[How to use the editor in a component]]
* [[Adding AJAX to your component]]
* [[Ajax using MooTools]]
* [[How to add breadcrumbs]]
* [[How to send email from components]]
* [[How to use the JToolBar class in the frontend]]
* [[Creating a toolbar for your component]]
* [[Creating a file uploader in your component]]
* [[Adding Javascript moo.fx to your component]]
* [[Adding view layout configuration parameters]]
* [[Using a custom image in the menu bar title]]
* [[How to implement XML-RPC in a component]]
* [[Using multiple models in an MVC component]]
* [[Adding ACL rules to your component]] {{JVer|1.7}}
* [[How to create a modal form field in 1.6/1.7]] {{JVer|1.6}} {{JVer|1.7}}
* [[JController and its subclass usage overview]] {{JVer|1.6}} {{JVer|1.7}}
* [[Managing Component Updates with Joomla!1.6 - Part 1]] {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
* [[Xml-rpc changes in Joomla! 1.6]] {{JVer|1.6}}
* [[How to create PDF views]]{{JVer|2.5}}
* [[Components:jform fields]]. and their usage {{JVer|2.5}}
</onlyinclude>

== Tutorials ==
List of all articles belonging to the categories "Tutorials" AND "Component Development"
<DPL>
noresultsheader=\n
format = ,\n* [[%PAGE%|%TITLE%]],,
category=Tutorials
category=Component Development
</DPL>

==FAQ==
List of all articles belonging to the categories "FAQ" AND "Component Development"
<DPL>
noresultsheader=\n
format = ,\n* [[%PAGE%|%TITLE%]],,
category=FAQ
category=Component Development
</DPL>

Archived:Managing Component Updates (How to use this example)

2012-06-10T21:47:39Z

Sm990: /* Summary */

Archived:Managing Component Updates (Component release files)

2012-06-10T21:42:50Z

Sm990: /* Version 1.3 */

Archived:Managing Component Updates (Component release files)

2012-06-10T21:41:27Z

Sm990: /* Version 1.1.1 */

Archived:Managing Component Updates (Component release files)

2012-06-10T21:39:55Z

Sm990: /* Version 1.0.j3 */

Archived:Managing Component Updates (Component release files)

2012-06-10T21:38:03Z

Sm990: /* Version 1.0 */

Archived:Managing Component Updates (Script.php)

2012-06-10T21:20:12Z

Sm990: /* The entire script.php file */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file. It is the same for all versions of com_democompupdate.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:19:59Z

Sm990: /* The entire script.php file */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file. It is the same for al versions of com_democompupdate.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:19:07Z

Sm990: /* The entire script.php file */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:18:47Z

Sm990: /* The entire script.php file */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}
</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:17:23Z

Sm990: /* postflight */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in all updates. This is how you would change revision-specific values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. This example sets these two values only on a new install, not on an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}
</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:14:16Z

Sm990: /* update */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// You can have the backend jump directly to the newly updated component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change revision-specific identification values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:12:44Z

Sm990: /* install */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change revision-specific identification values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T21:08:30Z

Sm990: /* preflight */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 is equal to or greater than the value in the manifest file. If an earlier Joomla version is in use, the install or update will abort. Try changing the version string in the manifest file file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// Following an install, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change revision-specific identification values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-06-10T20:58:08Z

Sm990: /* preflight */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 Joomla 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 string in the script.php file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Installing component manifest file version
$this->release = $parent->get( "manifest" )->version;

// Manifest file minimum Joomla version
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

// Show the essential information at the install/update back-end
echo 'Installing component manifest file version = ' . $this->release;
echo ' Current manifest cache commponent version = ' . $this->getParam('version');
echo ' Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
echo ' Current Joomla version = ' . $jversion->getShortVersion();

// abort if the current Joomla release is older
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// Following an install, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change revision-specific identification values during an update. The examples ''myparam2'' and ''myparam3'' represent component configuration parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Manifest file)

2012-06-10T20:49:30Z

Sm990: /* Joomla version */

Archived:Managing Component Updates (Manifest file)

2012-06-10T20:46:11Z

Sm990:

Archived:Managing Component Updates (Update SQL files)

2012-06-10T17:16:53Z

Sm990: /* Update SQL files */

Archived:Managing Component Updates (Script.php)

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 Joomla 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 string in the script.php file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Extract the version number from the manifest file
$this->release = $parent->get( "manifest" )->version;

// Find mimimum required joomla version from the manifest file
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '. $this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// Following an install, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change the component revision number during an update. The examples ''myparam2'' and ''myparam3'' show how you would treat parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that control component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Script.php)

2012-02-02T02:24:15Z

Sm990: /* postflight */

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 Joomla 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 string in the script.php file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Extract the version number from the manifest file
$this->release = $parent->get( "manifest" )->version;

// Find mimimum required joomla version from the manifest file
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '. $this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// Following an install, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change the component revision number during an update. The examples ''myparam2'' and ''myparam3'' show how you would treat parameters that you expect users to set, and you do not want to overwrite during an update. Parameters that define component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (How to use this example)

2012-02-02T02:18:33Z

Sm990:

Archived:Managing Component Updates (Component release files)

2012-02-02T02:18:05Z

Sm990:

Archived:Managing Component Updates (Update SQL files)

2012-02-02T02:17:37Z

Sm990:

Archived:Managing Component Updates (Script.php)

2012-02-02T02:17:09Z

Sm990:

{{review}}
{{RightTOC}}
This tutorial is for Joomla {{JVer|1.6}} {{JVer|1.7}}
== Articles in this series ==
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_1|Overview]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_2|Manifest file]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_3|Script.php]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_4|Update SQL files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_5|Component release files]]
* [[Managing_Component_Updates_with_Joomla!1.6_-_Part_6|How to use this example]]

== Script.php ==
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 ===
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 Joomla 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 string in the script.php file to a value greater than the Joomla version that you are using. Installs and updates should fail. This is what the version ''democompupdate_10j3.zip'' demonstrates.

In addition to failing, it is important to give the web site administrator useful information as to why the component installation failed. See the example below.
<source lang="php">
function preflight( $type, $parent ) {
$jversion = new JVersion();

// Extract the version number from the manifest file
$this->release = $parent->get( "manifest" )->version;

// Find mimimum required joomla version from the manifest file
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '. $this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}
</source>

=== install ===
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.
<source lang="php">
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// Following an install, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== update ===
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.
<source lang="php">
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
// Following an update, the backend can jump directly to the newly installed component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}
</source>

=== postflight ===
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 installs, and to set the values of hidden component parameters during installs and updates. Postflight can be used for any other action that must follow the install, update or discover_install actions.

This example defines component parameters in postflight. The value of ''my_param0'' is displayed in the component front-end. Both ''my_param0'' and ''my_param1'' are overwritten in updates. This is how you would change the component revision number during an update. The example ''myparam2'' is how you would treat parameters that you expect users to define, and you do not want to overwrite during an update. Parameters that define component operation would be treated this way.
<source lang="php">
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

</source>

=== uninstall ===
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, so returning false would be a waste of time.
<source lang="php">
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}
</source>

== The entire script.php file ==
This is the entire script.php file for version 1.0.
Note the definition of the variable ''$release''.
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

//the name of the class must be the name of your component + InstallerScript
//for example: com_contentInstallerScript for com_content.
class com_democompupdateInstallerScript
{
/*
* The release value to be displayed and checked against throughout this file.
*/
private $release = '1.0';

/*
* Find mimimum required joomla version for this extension. It will be read from the version attribute (install tag) in the manifest file
*/
private $minimum_joomla_release = '1.6.0';

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* preflight runs before anything else and while the extracted files are in the uploaded temp folder.
* If preflight returns false, Joomla will abort the update and undo everything already done.
*/
function preflight( $type, $parent ) {
// this component does not work with Joomla releases prior to 1.6
// abort if the current Joomla release is older
$jversion = new JVersion();

// Extract the version number from the manifest. This will overwrite the 1.0 value set above
$this->release=$parent->get("manifest")->version;

// Find mimimum required joomla version
$this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;

if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
return false;
}

// abort if the component being installed is not newer than the currently installed version
if ( $type == 'update' ) {
$oldRelease = $this->getParam('version');
$rel = $oldRelease . ' to ' . $this->release;
if ( version_compare( $this->release, $oldRelease, 'le' ) ) {
Jerror::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
return false;
}
}
else { $rel = $this->release; }

echo '' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '';
}

/*
* $parent is the class calling this method.
* install runs after the database scripts are executed.
* If the extension is new, the install method is run.
* If install returns false, Joomla will abort the install and undo everything already done.
*/
function install( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '';
// You can have the backend jump directly to the newly installed component configuration page
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
}

/*
* $parent is the class calling this method.
* update runs after the database scripts are executed.
* If the extension exists, then the update method is run.
* If this returns false, Joomla will abort the update and undo everything already done.
*/
function update( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '';
}

/*
* $parent is the class calling this method.
* $type is the type of change (install, update or discover_install, not uninstall).
* postflight is run after the extension is registered in the database.
*/
function postflight( $type, $parent ) {
// always create or modify these parameters
$params['my_param0'] = 'Component version ' . $this->release;
$params['my_param1'] = 'Another value';

// define the following parameters only if it is an original install
if ( $type == 'install' ) {
$params['my_param2'] = '4';
$params['my_param3'] = 'Star';
}

$this->setParams( $params );

echo '' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '';
}

/*
* $parent is the class calling this method
* uninstall runs before any other action is taken (file removal or database processing).
*/
function uninstall( $parent ) {
echo '' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '';
}

/*
* get a variable from the manifest file (actually, from the manifest cache).
*/
function getParam( $name ) {
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
$manifest = json_decode( $db->loadResult(), true );
return $manifest[ $name ];
}

/*
* sets parameter values in the component's row of the extension table
*/
function setParams($param_array) {
if ( count($param_array) > 0 ) {
// read the existing component value(s)
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
$params = json_decode( $db->loadResult(), true );
// add the new variable(s) to the existing one(s)
foreach ( $param_array as $name => $value ) {
$params[ (string) $name ] = (string) $value;
}
// store the combined new and existing values back as a JSON string
$paramsString = json_encode( $params );
$db->setQuery('UPDATE #__extensions SET params = ' .
$db->quote( $paramsString ) .
' WHERE name = "com_democompupdate"' );
$db->query();
}
}
}

</source>

== Contributors ==
*[[User:sm990|Kim Eckert]]
*[[User:tapaccos|Alex Tapaccos]]

[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[Category:Tutorials]]
[[Category:Component Development]]

Archived:Managing Component Updates (Manifest file)

2012-02-02T02:16:30Z

Sm990: