X-Cart:Upgrading

The X-Cart team regularly improves and updates the X-Cart shopping cart by releasing new software versions and branches. With each new release, X-Cart gains a series of fixes and advances that make the software even more powerful, efficient and secure. Some of these improvements only fine-tune the existing X-Cart behavior, but other change it dramatically by introducing new features and opportunities, affecting the software hard core, database structure and user interfaces. And it seems quite natural that at some point you may decide to upgrade your store to the latest version so that to be able to use all the advantages of newer releases.

To better understand X-Cart upgrades, read #General information on upgrading section.

Specially for those store owners who already use earlier X-Cart versions and want to upgrade their stores, together with new software versions we release special upgrade packs that allow store owners to iron differences between their existing copies of X-Cart and the latest X-Cart versions. Both the new releases and the upgrade packs are available for download to registered X-Cart license owners through their personal Help Desk accounts at https://secure.qtmsoft.com .

General information on upgrading

Understanding X-Cart upgrade procedure

In order to understand the X-Cart upgrade procedure you should first have a look at the X-Cart version numbering scheme, which is determined by the current software architecture. X-Cart uses the sequence-based software versioning scheme of three-sequence identifiers like 4.2.2 or 4.3.1. In the sequence, the first two numbers mean the major X-Cart version, which is commonly referred to as a branch, and the third number means the minor X-Cart version, the software version within a branch. The major version numbers get increased when there has been a significant revision of the software functionality, behavior and template structure while the minor version number is incremented when only minor features and significant fixes have been added to the software but the overall software structure and behavior have remained untouched. This stipulates two different approaches to the upgrade depending on whether you upgrade to a later minor version within one branch or to a later major version (branch).

Upgrading to a later minor version

When you upgrade the store to a later minor version within one branch (for example, from X-Cart 4.2.1 to X-Cart 4.2.2), you can smoothly upgrade the default software code, database and design. In order to upgrade the store you will need to apply an upgrade pack - a set of patch files - that will iron out the differences between your copy of X-Cart and the X-Cart version to which you upgrade. The packs are applied automatically through a special section of the X-Cart Admin area.

Nonetheless this task can become a more complicated one if you upgrade the store within one of the earlier branches like 3.5.x or 4.0.x as there may be no direct pack to upgrade from a given version of the store to the required version, and you will need to successively apply several upgrade packs until you upgrade the required version then. For example, if the current version of your store is X-Cart 4.0.6 and you want to upgrade to X-Cart 4.0.19, the latest version within the branch 4.0.x, first you will need to upgrade to version 4.0.17, then from version 4.0.17 to version 4.0.18, and eventually you will be able to upgrade to version 4.0.19. Besides, you will need to re-install the skin template and the add-on modules, if you use any.

Important: Take note that if your store utilizes some custom code or has serious design changes, the files and database tables that were modified within a custom development project will be skipped or updated partially, which is likely to damage the custom functionality and design, and even affect the default X-Cart functionality. If you are not sure whether the custom functionality and design will remain intact after the upgrade, consult the X-Cart Support team (see section [[X-Cart:Getting_Help Getting Help]).

Upgrading to a later major version (branch)

When you upgrade your store to a later major version (e.g. from X-Cart 4.2.x to X-Cart 4.3.x), you can only upgrade the default store database, but you will need to install a fresh copy of X-Cart and point it to the upgraded database. This approach is conditioned by the X-Cart architecture that changes significantly with every new branch leaving no technical feasibility to upgrade the software code and design automatically.

In order to upgrade the database, you need to run a special script that will convert the data in the database so that it could be used with a particular X-Cart version to which you upgrade the store. For convenience, a particular database structure is referred to in accordance with the X-Cart version that the database is compatible with. For example, the database version 4.2.1 means that the database can be used with X-Cart version 4.2.1.

Frustratingly, the set of available upgrade scripts is rather limited, and there may be no upgrade script that can convert the given database to the required one directly. In this case, you will need to convert your store database several times until you get the database that is compatible with the X-Cart version to which you upgrade your store. The list of available direct database upgrades is shown in the table below: The column on the left contains a source database version; the column on the right contains the list of direct database upgrades available for a particular source database.

Source X-Cart DB Version	Direct X-Cart DB Upgrades
3.5.10	X-Cart Branch 4.0.x * 4.0.1
3.5.12	X-Cart Branch 4.0.x * 4.0.6
3.5.14	X-Cart Branch 4.0.x * 4.0.12 X-Cart Branch 4.1.x * 4.1.11 * 4.1.12
4.0.19	X-Cart Branch 4.1.x * 4.1.11 * 4.1.12
4.1.11	X-Cart Branch 4.2.x * 4.2.0
4.1.12	X-Cart Branch 4.2.x * 4.2.1 * 4.2.2 X-Cart Branch 4.3.x * 4.3.0
4.2.3	X-Cart Branch 4.3.x * 4.3.0

In the situation when you have to to upgrade the database several times, it is recommended that you follow these simple rules:

• When you have to upgrade within a branch, carry out the in-branch upgrade on a more recent branch, if there is an alternative.

The upgrade engine improves with each new X-Cart release, and the upgrade on a more recent branch keeps a risk of a failure or mistake to a minimum. For example, when you upgrade the database for X-Cart 4.1.11 to the database for X-Cart 4.2.2 the two alternatives are as follows:

(A) 4.1.11 -> 4.2.1 -> 4.2.2

(B) 4.1.11 -> 4.1.12 -> 4.2.2

(A) is the recommended alternative as the in-branch upgrade is carried out on a more recent branch X-Cart 4.2.x.

• When you need to leap over a branch (e.g. from X-Cart 4.1.x to X-Cart 4.3.x), minimize the number of branch-to-branch upgrades.

With a branch-to-branch upgrade the data in the database is converted, which theoretically increases a possibility of a fault or data loss. For example, when you upgrade the database for X-Cart 4.1.11 to the database for X-Cart 4.3.0 the two alternatives are as follows:

(A) 4.1.11 -> 4.1.12 -> 4.3.0

(B) 4.1.11 -> 4.2.1 -> 4.3.0

(A) is the recommended alternative as it supposes only one branch-to-branch upgrade while the (B) alternative supposes two branch-to-branch upgrades.

Important: You must be aware that with the upgrade to a later major version it is impossible to transfer the custom code and design automatically. So if you use any in your store, you will need to re-implement the custom code and design after the upgrade, which is rather a resource-consuming task that requires adequate experience in PHP, HTML and MySQL.

Associated difficulties

New releases not only enrich the software with new features and capabilities, but they get rid of obsolete elements and techniques that are no longer in great demand. But you may have gotten used to the current logics and behavior of the X-Cart version that you use; or you may extensively use the elements that are not supported in later X-Cart releases. In such a situation, the upgrade may involve extra inconvenience. It is recommended that you study the CHANGELOG, which is updated with each new release and is included into every distribution package. The CHANGELOG provides a complete list of fixes and improvements that were introduced to a new X-Cart release.

Another critical issue about the upgrades is that seamless upgrade is only possible if the store uses a default database and template structure, and has only minor changes like its own store logo and similar. Yet, if the store has serious design changes or it utilizes some custom code and third-party add-on modules that interfere with the original software behavior, you will need to re-implement custom code and design after the upgrade, which requires adequate experience in PHP, HTML and MySQL. So, if you use some custom functionality, find out if it is possible to keep it after the upgrade.

On the whole, upgrading X-Cart is a resource-consuming task, which demands that you understand what you are going to do and why. The rule here is not to upgrade to a newer version if there is no need to do this and you are satisfied with how the store works at the moment.

If you decide that your store needs to be upgraded, be honest when estimating your abilities: If you are not sure you have enough resources to perform this task on your own, do not start it. Leave it to professional engineers, and it will save your time, money and nerves.

Upgrading X-Cart step-by-step

• Consider the environment and make a development copy of your store
• Perform the upgrade procedure
• Complete post-upgrade tasks