1   2   3

6. Applying the upgrade patch (Step 2 of 2). Now that patch applicability has been checked, we proceed to the next step of upgrading X-Cart. Clicking on the Apply patch button initiates the process of applying the upgrade patch.

This process can involve the following steps:

1) patch_pre.php code execution
2) *.diff files application
3) database modifications (execution of SQL commands from the file patch.sql)
4) patch_post.php code execution
5) updating of X-Cart version in the database (Do not confuse with the file VERSION in X-Cart root - this file has nothing to do with the information about X-Cart version in the database!)

It must be pointed out that each of these five steps is optional and is not necessarily included into upgrade (for example, steps #1 and #4 are very rare, #3 is also not so often). The presence or absence of this or that step depends only on the decision of upgrade developers. However, if a step is meant to be in the upgrade, but errors occur during this step - upgrade patch application fails.

The process of upgrade patch application is shown on the screen:

Picture 10: Applying upgrade patch.

If the application of the upgrade patch to some files fails, you will get a notice about that in the results table: the files that could not be patched correctly get the status 'could not patch'.

Picture 11: Applying patch (Step 2 of 2: Applying the patch).

Patch results show what files the patch was successfully applied to, and what files failed to be patched. You can see patch log for details (patch log is displayed in this form, but you can also view it in the file xcart_dir/templates_c/upgrade/patch.log).

In our example an error occurred: VERSION could not be patched (IMPORTANT! this VERSION is not the file VERSION located in X-Cart root directory, but a record of X-Cart version in the database)

We cannot proceed with this error, so all we can do is click on the Go back button. This takes us back to the very beginning of the upgrade procedure when patch applicability is tested (Step 1 of 2). This time we wait for X-Cart to state that VERSION could not be patched and remove the tick from the 'Tick here if you want to try to apply the patch to these files' check box. Next, we click on Apply patch and watch the progress of upgrade patch application on the screen. The files patched during the first run of upgrade application are marked 'already patched' (which is normal) and VERSION again gets the status 'could not patch' (with the only difference that this time it is ignored).

Picture 12: Applying patch (Step 2 of 2: Applying the patch).

Patch results show that upgrade patch has been successfully applied to all the files except VERSION (it will have to be patched manually).

Clicking on Finish gets you back to the 'Patch/Upgrade center' page.

7. If X-Cart failed to apply upgrade patch to one or more files or to apply SQL patch to the database automatically and you saw error messages in red in the 'Applying patch' results form, it is time to try and patch these files and/or database info manually. You should understand the conception of using DIFF files and be familiar with X-Cart database structure to perform this operation!

If a file could not be patched, use PATCH LOG to find out which of the patch hunks failed to apply. Open the file that could not be patched in a text editor. In the 'upgrade' folder find a DIFF for this file (if you look at the structure of an upgrade patch, you will see that DIFF files bear the names of the source files to which they should be applied and have the same location relative to the upgrade patch directory as the source files have to the root). Open the DIFF file in the text editor and compare the contents of the hunk that could not be applied with the corresponding part of the source code. Each hunk begins with a string similar to this one:

@@ -97,6 +97,7 @@

where -97 is the line of the block in the corresponding source file that needs to be modified. Following this line are lines marked by "+" and "-". Find in the source file the line marked by "-" in the DIFF file and replace it by the line from the DIFF file that is marked by "+". Save the file.

Note: if the line to be replaced has custom modifications you should combine them with new version modifications.

If database info could not be patched, use PATCH LOG to find out what has gone wrong. Open patch.sql file from upgrade patch folder and execute the necessary SQL queries.

After you have successfully applied the SQL patch, update X-Cart version info in the database by using the following SQL query:

> UPDATE xcart_config SET value='x.x.x' WHERE name='version'

where x.x.x. is the upgrade target version number, for example: value='3.5.8'

8. If manual application of the upgrade patch to a file or to SQL database fails, we recommend you restore your X-Cart (See 'Restoration procedure' section of the manual for details) and order upgrade services from X-Cart team.

After you have successfully restored your X-Cart, follow the 'Security' section.

Restoration procedure

You may need to restore your cart to the original state if something goes wrong during the upgrade procedure. To restore X-Cart take the following steps:

1. Uncompress the saved X-Cart archive into X-Cart folder. On Unix-based servers with a terminal access, you can do it using the command:

> gunzip < xcart.tgz | tar -xvf -

2. Restore the database from the database backup. In order to do so log into X-Cart administrative area and select DB Backup/Restore from the Administration menu. If as a result of the upgrade procedure the cart stops functioning you can restore the database using MySQL command line utility. If you do not have access to MySQL command line utility, take the following steps to restore X-Cart:

1) Reinstall the original X-Cart from the distributive.
2) Restore the database using DB Backup/Restore from the Administration menu.
3) Uncompress the saved X-Cart archive into X-Cart folder.

After upgrade

After you have successfully upgraded your X-Cart, please check the functionality of the updated script files, templates and database by running X-Cart in both administrative and customer mode. If you experience any problems with the upgraded X-Cart you need to restore the previous version of X-Cart and X-Cart database. See the 'Restoration procedure' section of the manual for details.

For security reasons it is highly recommended to restore the original permissions for patched files.

After the upgrade procedure has been successfully completed or after X-Cart has been restored, remove all the temporary files from the '<xcart root folder>/templates_c' directory.

Revision date: Jan 31, 2006

1   2   3