X-Cart:Applying Patches

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. Sign in to the Admin area of your X-Cart and go to the 'Patch/Upgrade' section. You see the 'Apply patch' form:

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 applying 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 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:

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, as described here.

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

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

• If you are using a UNIX server
• If you are using a Windows server

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.

If you cannot apply the patch in these ways it means the file that needs to be patched has been modified or this file is from another version of X-Cart and cannot be patched by this patch. Ask technical support to help you.

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, or already have such file, skip this step.

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

4. In the 'Apply SQL patch' form select your file by clicking 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.

If no errors occurred, click Finish.