Actions

J2.5

Difference between revisions of "Managing Component Updates (Script.php)"

From Joomla! Documentation

m (install)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{review}}
+
{{version/tutor|2.5}}{{Chunk:Managing Component Updates - Contents}}{{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 ==
 
== 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.
 
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.
+
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 ===
 
=== preflight ===
Line 78: Line 69:
 
function update( $parent ) {
 
function update( $parent ) {
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '</p>';
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '</p>';
// Following an update, the backend can jump directly to the newly installed component configuration page
+
// You can have the backend jump directly to the newly updated component configuration page
$parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
+
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
 
}
 
}
 
</source>
 
</source>
Line 88: Line 79:
 
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.
 
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.
+
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">
 
<source lang="php">
 
function postflight( $type, $parent ) {
 
function postflight( $type, $parent ) {
Line 94: Line 85:
 
$params['my_param0'] = 'Component version ' . $this->release;
 
$params['my_param0'] = 'Component version ' . $this->release;
 
$params['my_param1'] = 'Another value';
 
$params['my_param1'] = 'Another value';
 
+
 
// define the following parameters only if it is an original install
 
// define the following parameters only if it is an original install
 
if ( $type == 'install' ) {
 
if ( $type == 'install' ) {
Line 100: Line 91:
 
$params['my_param3'] = 'Star';
 
$params['my_param3'] = 'Star';
 
}
 
}
 
+
 
$this->setParams( $params );
 
$this->setParams( $params );
 
+
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '</p>';
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '</p>';
}
+
}
 
+
 
</source>
 
</source>
  
Line 117: Line 107:
  
 
== The entire script.php file ==
 
== The entire script.php file ==
This is the entire script.php file for version 1.0.
+
This is the entire script.php file. It is the same for all versions of com_democompupdate.
Note the definition of the variable ''$release''.
+
 
<source lang="php">
 
<source lang="php">
 
<?php
 
<?php
 
// No direct access to this file
 
// No direct access to this file
 
defined('_JEXEC') or die('Restricted access');
 
defined('_JEXEC') or die('Restricted access');
 
+
 
//the name of the class must be the name of your component + InstallerScript
 
//the name of the class must be the name of your component + InstallerScript
 
//for example: com_contentInstallerScript for com_content.
 
//for example: com_contentInstallerScript for com_content.
 
class com_democompupdateInstallerScript
 
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.
 
* $parent is the class calling this method.
Line 145: Line 124:
 
*/
 
*/
 
function preflight( $type, $parent ) {
 
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();
 
$jversion = new JVersion();
  
                // Extract the version number from the manifest. This will overwrite the 1.0 value set above
+
// Installing component manifest file version
                $this->release=$parent->get("manifest")->version;
+
$this->release = $parent->get( "manifest" )->version;
               
+
                // Find mimimum required joomla version
+
// Manifest file minimum Joomla version
                $this->minimum_joomla_release=$parent->get("manifest")->attributes()->version;  
+
$this->minimum_joomla_release = $parent->get( "manifest" )->attributes()->version;  
  
 +
// Show the essential information at the install/update back-end
 +
echo '<p>Installing component manifest file version = ' . $this->release;
 +
echo '<br />Current manifest cache commponent version = ' . $this->getParam('version');
 +
echo '<br />Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
 +
echo '<br />Current Joomla version = ' . $jversion->getShortVersion();
 +
 +
// abort if the current Joomla release is older
 
if( version_compare( $jversion->getShortVersion(), $this->minimum_joomla_release, 'lt' ) ) {
 
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);
 
Jerror::raiseWarning(null, 'Cannot install com_democompupdate in a Joomla release prior to '.$this->minimum_joomla_release);
 
return false;
 
return false;
 
}
 
}
 
+
 
// abort if the component being installed is not newer than the currently installed version
 
// abort if the component being installed is not newer than the currently installed version
 
if ( $type == 'update' ) {
 
if ( $type == 'update' ) {
Line 170: Line 154:
 
}
 
}
 
else { $rel = $this->release; }
 
else { $rel = $this->release; }
+
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '</p>';
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '</p>';
 
}
 
}
 
+
 
/*
 
/*
 
* $parent is the class calling this method.
 
* $parent is the class calling this method.
Line 185: Line 169:
 
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
 
// $parent->getParent()->setRedirectURL('index.php?option=com_democompupdate');
 
}
 
}
 
+
 
/*
 
/*
 
* $parent is the class calling this method.
 
* $parent is the class calling this method.
Line 194: Line 178:
 
function update( $parent ) {
 
function update( $parent ) {
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '</p>';
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '</p>';
 +
// 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.
 
* $parent is the class calling this method.
Line 224: Line 210:
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '</p>';
 
echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '</p>';
 
}
 
}
 
+
 
/*
 
/*
 
* get a variable from the manifest file (actually, from the manifest cache).
 
* get a variable from the manifest file (actually, from the manifest cache).
Line 230: Line 216:
 
function getParam( $name ) {
 
function getParam( $name ) {
 
$db = JFactory::getDbo();
 
$db = JFactory::getDbo();
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
+
$db->setQuery('SELECT manifest_cache FROM #__extensions WHERE name = "com_democompupdate"');
 
$manifest = json_decode( $db->loadResult(), true );
 
$manifest = json_decode( $db->loadResult(), true );
 
return $manifest[ $name ];
 
return $manifest[ $name ];
 
}
 
}
 
+
 
/*
 
/*
 
* sets parameter values in the component's row of the extension table
 
* sets parameter values in the component's row of the extension table
Line 242: Line 228:
 
// read the existing component value(s)
 
// read the existing component value(s)
 
$db = JFactory::getDbo();
 
$db = JFactory::getDbo();
$db->setQuery('SELECT params FROM #__extensions WHERE name = '.$db->quote('com_democompupdate'));
+
$db->setQuery('SELECT params FROM #__extensions WHERE name = "com_democompupdate"');
 
$params = json_decode( $db->loadResult(), true );
 
$params = json_decode( $db->loadResult(), true );
 
// add the new variable(s) to the existing one(s)
 
// add the new variable(s) to the existing one(s)
Line 252: Line 238:
 
$db->setQuery('UPDATE #__extensions SET params = ' .
 
$db->setQuery('UPDATE #__extensions SET params = ' .
 
$db->quote( $paramsString ) .
 
$db->quote( $paramsString ) .
' WHERE name = '.$db->quote('com_democompupdate'));
+
' WHERE name = "com_democompupdate"' );
 
$db->query();
 
$db->query();
 
}
 
}
 
}
 
}
 
}
 
}
 
 
</source>
 
</source>
  
Line 267: Line 252:
 
[[Category:Joomla! 1.7]]
 
[[Category:Joomla! 1.7]]
 
[[Category:Joomla! 2.5]]
 
[[Category:Joomla! 2.5]]
[[Category:Tutorials]]
 
 
[[Category:Component Development]]
 
[[Category:Component Development]]

Latest revision as of 07:04, 24 May 2013

Contents

Copyedit.png
This Page Needs Your Help

This page is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.


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.

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 '<p>Installing component manifest file version = ' . $this->release;
        echo '<br />Current manifest cache commponent version = ' . $this->getParam('version');
        echo '<br />Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
        echo '<br />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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '</p>';
}

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.

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

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.

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

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.

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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '</p>';
}

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.

function uninstall( $parent ) {
        echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '</p>';
}

The entire script.php file

This is the entire script.php file. It is the same for all versions of com_democompupdate.

<?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 '<p>Installing component manifest file version = ' . $this->release;
                echo '<br />Current manifest cache commponent version = ' . $this->getParam('version');
                echo '<br />Installing component manifest file minimum Joomla version = ' . $this->minimum_joomla_release;
                echo '<br />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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_PREFLIGHT_' . $type . ' ' . $rel) . '</p>';
        }
 
        /*
         * $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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_INSTALL to ' . $this->release) . '</p>';
                // 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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_UPDATE_ to ' . $this->release) . '</p>';
                // 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 '<p>' . JText::_('COM_DEMOCOMPUPDATE_POSTFLIGHT ' . $type . ' to ' . $this->release) . '</p>';
        }
 
        /*
         * $parent is the class calling this method
         * uninstall runs before any other action is taken (file removal or database processing).
         */
        function uninstall( $parent ) {
                echo '<p>' . JText::_('COM_DEMOCOMPUPDATE_UNINSTALL ' . $this->release) . '</p>';
        }
 
        /*
         * 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();
                }
        }
}

Contributors