X-Cart:Applying Patches

From X-Cart 4 Classic
Revision as of 09:30, 14 September 2010 by Ivka (talk | contribs) (To apply a patch manually)
Jump to: navigation, search

Overview

X-Cart provides an interface that allows you to apply patches. The two types of patches that you might need to apply in X-Cart are file patches and SQL patches.

IMPORTANT! It is recommended to make a backup copy of all PHP scripts, templates and create a database dump before applying any patches. Please use Patch/Upgrade function ONLY if you absolutely understand what you are doing.

Applying File Patches

The 'Patch/Upgrade center' section of X-Cart allows you to apply file patches supplied by X-Cart developers using the Admin area of your store. A patch can be applied from a patch file or from a URL.

Applying the patch can be done in several ways: via X-Cart Admin area, by issuing the command 'patch' or manually.

To apply a patch via X-Cart Admin area

1. BACK UP YOUR STORE!

2. Set write permissions for the files that will be patched.

3. Save the text of your patch to a file (e.g. patch.diff). If you are planning to use a patch from a certain URL, skip this step.

4. log in to the Admin area of your X-Cart and go to the 'Patch/Upgrade' section. You see the 'Apply patch' form:


Apply patch.gif


5. In the 'Apply patch' form select your file by clicking on the Browse button. Alternatively, you can enter the patch URL into the appropriate field.

If you are going to apply a new patch, 'Reverse' selectbox should be set to 'No'. Selecting 'Yes' will lead to the removal of the specified patch that has already been applied.

To start the application of the patch click the Apply button.

The procedure of patch application includes two basic steps:

1. Testing patch applicability (Step 1 of 2). First X-Cart will check the presence of executable permissions for the patch tool, then patch checksums and permissions for each file the patch must be applied to. Then the results of patch applicability testing will be shown to you in the 'Applying patch' form.

If your Patch/Upgrade center detects any problems (errors - marked in red), you will not be able to proceed with applying your patch until these problems are resolved. You will have to go back, make the necessary corrections and run the patch applicability test once again.

2. Applying the patch (Step 2 of 2). Clicking on the Apply patch button initiates the process of applying the patch. During this process the differences contained in the *.diff files are implemented in the source code of your X-Cart.

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


Applying patch5.gif


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.

The following problems may arise:

  • checksum error - patch contents is corrupted;
  • non-writable - writable permission has not been given to the file, please give it writable permission;
  • not a file - the target is not a file;
  • not exists - the necessary file is missing;
  • could not patch - the patch cannot be applied to this file automatically, because it has been significantly modified, the patch should be applied to this file manually

When the patch has been successfully applied, click on Finish to get back to the 'Patch/Upgrade center' page.

Note: Do not forget to change permissions for the patched files.

To apply a patch by issuing the command 'patch'

  1. Save the text of your patch to a file (e.g. patch.diff).
  2. Copy this file (patch.diff) to the directory where X-Cart is installed.
  3. Issue the command 'patch --dry-run -p1 < patch.diff' to check the patch applicability.
  4. If there are no errors during the check-up, apply the patch by issuing the command 'patch -p1 < patch.diff'.

You can read more about 'patch' command in the manual (man patch, info patch).

If the text of the patch contains header lines like "Index: include/func/func.category.php", use -p0 option in the commands, i.e. 'patch --dry-run -p0 < patch.diff' and 'patch -p0 < patch.diff'.

See also: How to apply patches manually.

To apply a patch manually

If a patch application failed in the first two ways (this may be caused by redundant spaces or conversion problems) you can try to apply the patch manually.

What is diff (patch) file?

Diff (or patch) is a file that displays the changes made per line for text files, and in particular, for X-Cart source files.

Diff can include changes for several files. The name of each modified file is specified under a header line that may look something like this:

Index: include/func/func.category.php

The above header line indicates that the diff displays the changes for <xcart_dir>/include/func/func.category.php file.

Each header line is then followed with one or several "hunks". Each "hunk" starts with a line that may look something like this:

@@ -942,8 +940,7 @@

where:

  • 942 - indicates the number of the first line in the original code (before patch application)
  • 8 - indicates the number of lines in the original code (before patch application)
  • 940 - indicates the number of the first line in the changed code (after patch application)
  • 7 - indicates the number of lines in the changed code (after patch application)

Then follows the file code that includes lines marked with the "+" and "-" signs.

Lines marked with "+" are the lines that you need to add in the file to be patched.

Lines marked with "-" are the lines that you need to remove from the file to be patched.

Example of diff file

Index: include/func/func.category.php
@@ -585,9 +585,7 @@

$cat = abs(intval($cat));

-    $to_search =
-    $search_condition =
-    $join_tbl = array();
+    $to_search = $search_condition = $join_tbl = array();

$from = "$sql_tbl[categories] AS node ";

@@ -942,8 +940,7 @@
'c.rpos'
);

-    $search_condition =
-    $join_tbl = array();
+    $search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

General instructions

1. Open the diff file in a text editor.

2. Edit the file (in our example, include/func/func.category.php):

  • Find the lines marked with "-" in the text of the patch and remove them.
  • Insert the lines marked with "+" in the text of the patch.

In our example, the original code (before applying the patch) would look like:

line 585:
line 586:    $cat = abs(intval($cat));
line 587:
line 588:    $to_search =
line 589:    $search_condition =
line 590:    $join_tbl = array();
line 591:
line 593:    $from = "$sql_tbl[categories] AS node ";
line 594:
...
line 942:        'c.rpos'
line 943:    );
line 944:
line 945:    $search_condition =
line 946:    $join_tbl = array();
line 947:
line 948:    if ($current_area == 'A' || $current_area == 'P') {
line 949:

Total lines: 9 and 8 in each hunk correspondingly.

The changed code (after applying the patch) would look like:

line 585:
line 586:    $cat = abs(intval($cat));
line 587:
line 588:    $to_search = $search_condition = $join_tbl = array();
line 589:
line 590:    $from = "$sql_tbl[categories] AS node ";
line 591:
...
line 940:        'c.rpos'
line 941:    );
line 942:
line 943:    $search_condition = $join_tbl = array();
line 944:
line 945:    if ($current_area == 'A' || $current_area == 'P') {
line 946:

Total lines: 7 and 7 in each hunk correspondingly.

Understanding the process

In simple words, the patch application procedure for each hunk is as follows:

  • Search for the code to be replaced around (above and below) the expected line.
  • If found, change it to the new code.

Let us take another look at the second hunk of the example patch provided above to understand the process:

@@ -942,8 +940,7 @@
'c.rpos'
);

-    $search_condition =
-    $join_tbl = array();
+    $search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {
  • Original code to search for (8 lines of code around the line 942):
'c.rpos'
);

$search_condition =
$join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

  • New code to change to (7 lines of code):
'c.rpos'
);

$search_condition = $join_tbl = array();

if ($current_area == 'A' || $current_area == 'P') {

The built-in patch/upgrade utility basically works in the same way.

Applying SQL Patches

The 'Patch/Upgrade center' section of X-Cart allows you to apply SQL patches to your database using the Admin area of your store.

To apply an SQL patch:

1. BACK UP YOUR STORE!

2. Save the text of your patch to a file. If you are planning to use a patch from a certain URL, skip this step.

3. log in to the Admin area of your X-Cart and go to the 'Patch/Upgrade' section. Scroll down to the 'Apply SQL patch' form.


Apply sql patch.gif


4. In the 'Apply SQL patch' form select your file by clicking on the Browse button. Alternatively, you can enter the patch URL or enter SQL query(ies). To start applying the patch, click the Apply button.

5. The text of the patch will be shown to you in the 'Patch text' field.

Click on Apply patch to continue.

6. The results of patching your database will be shown to you.


Applying sql patch2.gif


If no errors occurred, click on Finish.