View source for Managing Component Updates

{{version/tutor|2.5}}{{Chunk:Managing Component Updates - Contents}}{{review}}
This component demonstrates how a component developer can use the features in Joomla 1.6 (and higher) to help the web site administrator correctly update the component.  Capabilities that are implemented in this demo package include:
# Confirming that the correct version of Joomla is installed before allowing an install or update of the component.
# Confirming that the correct version of the component is installed before allowing an update of the component.
# Controlling the sequence of SQL updates, when the user updates the component over multiple release versions.
# Show where the component developer can create custom code that will execute before and after component install, update, discover_install and uninstall.
# Demonstrate how to create and update component parameters during the component install and update process.

== Intro ==
There are two concerns when distributing component updates:
# Making sure that the correct update is selected for installation.  This selection depends on the version currently installed, and the desired version following the update.  Actions include both selecting appropriate updates and denying inappropriate updates.  The update actions may require multiple sequential steps, each implementing a separate set of update commands.
# Ensuring that the updates are correctly installed, and taking the appropriate action if they fail.
Joomla manages much of this process, but depends on the component developer to capture the version dependencies.  Additionally, the component may have unique update requirements that need to be enforced.
There are two parts of an install or update.
# Files.  During an update, Joomla completely replaces the files of the existing version with the files of the new version.  There is no incremental file update inherent in Joomla.  The component developer can implement this functionality by creating custom update code, if desired.
# Database.  During an update, Joomla can execute SQL commands to incrementally modify the component database.  The component developer maintains files with SQL commands that are necessary to modify the database from each older version to a newer version.
After becoming familiar with this example, the component developer should study the Joomla JinstallerComponent source code.  This is the best way to become familiar with the sequences and dependencies in the install, update, discover_install and uninstall processes.
The new update methods in Joomla 1.6 give the component developer the ability to implement complex, custom checks, abort conditions and installation sequences.

Parts 2 through 6 of this document describe the various sections of the software that the component developer must create to implement the features described in this document.

== This example ==
Files in this example implement an initial install and two subsequent updates of a component.  Included are a minimal front-end to allow the user to observe the results of correct and incorrect updates.  There is no component back-end.

This is a simple component.  You can implement your custom code here and observe the results prior to implementing it in your component.
This example is for a component.  Much of the example applies to other extensions, but those are not described here.

This example was developed on ''Joomla! 1.7.3 Stable''.

=== Version 1.0 ===
This is the initial component version.  Joomla will detect that there is no existing component with files in this directory and will use the install function.
If you have a more recent version of this component installed, the custom update code will not allow version 1.0 to be installed.  This is not a feature inherent to Joomla.  The component developer must implement it in custom code.

=== Version 1.0j3 ===
This is a variation of the initial 1.0 version.  It requires that Joomla 3.0 or higher be installed.  It is intended that installing this version will fail, showing how this Joomla version check operates.

=== Version 1.1.1 ===
This can be implemented either as an original install or an update from version 1.0.  If you do not install version 1.0, then Joomla will use the install function for this version.  If you have installed version 1.0, then Joomla will use the update function.
Like the description above for version 1.0, the custom code in this example will not allow an update to 1.1.1 if the existing installed version is 1.3.

=== Version 1.3 ===
Just as in version 1.1.1, this version can be installed as an original install or as an update to an existing version.  With this example, you can update to version 1.3 from either the original 1.0 version or from the intermediate 1.1.1 version.

=== Front-end ===
The front-end is a simple display of three fields.  The field at the top of the page is a table that shows the contents of the component database.  This database is a simple list of major component versions.  There is one row in the table for each major version, with the latest installed minor version string stored (and displayed) for each major version.  As the administrator updates this component, update SQL modifies the minor version string in the database. This is the display after version 1.3 has been installed or updated.

<blockquote>
<table style='border-style:solid;border-width:thin;padding:1em;'><tr><td>
<table border=1>
<tr style='background-color:#ccccff'><th>Index</th><th>Value</th></tr>
<tr><td>1</td><td>1.1.1</td></tr>
<tr><td>2</td><td>1.2.1</td></tr>
<tr><td>3</td><td>1.3</td></tr>
</table>

Files: 1.3

Param: Component version 1.3
</td></tr></table>
</blockquote>

Below the table is a line of text that shows the release string as defined in the component files.  If the sequence of updates is implemented correctly, the release string displayed from the files will match the release string on the last (bottom) row of the table.

At the bottom of the page is a line of text that shows the value of the component parameter ''my_param0''.  This parameter is defined in the script.php file during the install or update process.  It should match the release string shown in the line above.

The front-end on this example is a convenient way to confirm that the files and the database are synchronized, and that the update process was correctly executed.

== version_compare ==
See PHP documentation: [[php:version_compare]]

Joomla uses the PHP function
<source lang="php">
version_compare( string $version1 , string $version2 [, string $operator ] )
</source>
to determine if any SQL file(s) should be executed on an update, and to determine the order of execution for those files.  For this reason, the version string in your manifest file should follow the conventions that this command uses.  From the PHP manual:

: The function first replaces _, - and + with a dot . in the version strings and also inserts dots . before and after any non number so that for example '4.3.2RC1' becomes '4.3.2.RC.1'. Then it splits the results like if you were using explode('.', $ver). Then it compares the parts starting from left to right. If a part contains special version strings these are handled in the following order: any string not found in this list < dev < alpha = a < beta = b < RC = rc < # < pl = p. This way not only versions with different levels like '4.1' and '4.1.2' can be compared but also any PHP specific version containing development state. 

Use the optional $operator variable to perform a specific version string comparison that your code may require.  Allowed values for $operator are:

: <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne

In the script.php file, the component developer can use the same PHP version_compare function to execute code specific to a version, or to abort the update.

<source lang="php">
if ($type == 'update')
{
	if (version_compare($this->release, $oldRelease, 'le'))
        {
		JError::raiseWarning(null, 'Incorrect version sequence. Cannot upgrade ' . $rel);
		
		return false;
	}
}
</source>

== Component parameters ==
The ''postflight'' function in the script.php file is a good place to define or update the values of component parameters.  This example has a ''setParams'' function for this purpose.  Joomla stores the parameters as a JSON string in the ''params'' field in the ''extensions'' table.  The ''setParams'' function first converts the existing JSON string to a PHP array.  Additions or modifications are made to the array, then it is converted back to a JSON string and written to the ''extensions'' table.
<source lang="php">
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>

== Component files ==
The install zip files for the four versions can be individually downloaded from JoomlaCode.org.
* [http://joomlacode.org/gf/download/frsrelease/16495/74511/democompupdate_10.zip democompupdate_10.zip]
* [http://joomlacode.org/gf/download/frsrelease/16495/74512/democompupdate_10j3.zip democompupdate_10j3.zip]
* [http://joomlacode.org/gf/download/frsrelease/16495/74513/democompupdate_111.zip democompupdate_111.zip]
* [http://joomlacode.org/gf/download/frsrelease/16495/74514/democompupdate_13.zip democompupdate_13.zip]

You need to download all four of these to fully exercise the various update features.

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

<noinclude>
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Development]]
[[Category:Joomla! 2.5]]
</noinclude>