X-Cart:Upgrading

The X-Cart team regularly improves and updates the X-Cart shopping cart by releasing new software versions. 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, whereas other ones change it dramatically by introducing new features and opportunities, which involves considerable changes to the software 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 to take advantage of the great new features.

Specially for those store owners who already use X-Cart and want to upgrade their stores, with the release of each new X-Cart software version we release special upgrade packs which can be used to bring the advantages of the latest release to existing X-Cart copies of earlier 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.

The information below will hopefully give you a better understanding of X-Cart upgrades.

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 a 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 the branch, and the third number means the minor X-Cart version, which is the software version within the branch. The major version numbers are increased when there has been a significant revision of the software functionality, behavior and template structure, whereas 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 are upgrading. The packs are applied automatically through a special section of the X-Cart Admin area.

Nonetheless, this task can become more complicated if you are upgrading 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 to the required version. For example, if the current version of your store is X-Cart 4.0.6, and you want to upgrade it to X-Cart 4.0.19, which is the latest version within the 4.0.x branch, first you will need to upgrade from version 4.0.6 to 4.0.17, then from 4.0.17 to 4.0.18, and only after that 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 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. There are no ready-made upgrade packs to be used on your X-Cart copy; instead, you 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 each new major release 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 will be compatible with the X-Cart version to which you are going to upgrade your 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, database version 4.2.1 means that this database can be used with X-Cart version 4.2.1.

Unfortunately, the set of available upgrade scripts is rather limited, and there may not be an upgrade script that will convert your given database to the version you require directly. In this case you will need to convert your store database several times until you get a database compatible with the desired X-Cart version.

The table below provides a list of available direct database upgrades: the column on the left contains source database versions; the column on the right shows direct database upgrades available for each particular source database version.

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 X-Cart Branch 4.4.x * 4.4.0 X-Cart Branch 4.5.x * 4.5.0
4.2.3	X-Cart Branch 4.3.x * 4.3.0 X-Cart Branch 4.4.x * 4.4.0 X-Cart Branch 4.5.x * 4.5.0
4.3.2	X-Cart Branch 4.4.x * 4.4.0 X-Cart Branch 4.5.x * 4.5.0
4.4.5	X-Cart Branch 4.5.x * 4.5.0

In the situation when you have to upgrade the database several times successively, there may be more than one upgrade paths available. Please follow these recommendations for choosing the optimal upgrade path:

• Among the alternative upgrade paths involving an upgrade within a branch, choose the one in which the upgrade within a branch is carried out on a more recent branch.

The upgrade engine improves with each new X-Cart release, and upgrading on a more recent branch keeps the risk of failure 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 alternative paths are as follows:

(A) 4.1.11 -> 4.2.0 -> 4.2.2

(B) 4.1.11 -> 4.1.12 -> 4.2.2

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

• When you need to skip 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 each branch-to-branch upgrade the data in the database is converted, which theoretically increases the possibility of a fault or data loss. Thus, the fewer times you upgrade your database from branch to branch, the better. For example, when you upgrade the database for X-Cart 4.1.11 to the database for X-Cart 4.3.0, the two alternative paths are as follows:

(A) 4.1.11 -> 4.1.12 -> 4.3.0

(B) 4.1.11 -> 4.2.0 -> 4.3.0

(A) is the recommended path, as it involves only one branch-to-branch upgrade, whereas (B) involves 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 also get rid of outdated elements and techniques that are no longer in great demand. If you have gotten used to the logics and behavior of your current X-Cart version, or if you extensively use the elements that are not supported in later X-Cart releases, an 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 the new X-Cart release.

Another critical issue with X-Cart 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 the like. Yet, if the store has serious design changes, or if 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 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 to X-Cart 4.5.x step by step

Upgrading from version 4.5.0 or later

If the version of X-Cart on which your current store is based is 4.5.0 or later, to upgrade your store to a later minor version within the 4.5.x branch you will need to follow these steps:

1. Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
2. Obtain an upgrade pack for the direct upgrade from your current version to the desired version. For details, see the chapter Obtaining Upgrade Packs and Database Upgrade Scripts.
3. Apply the upgrade pack to your X-Cart installation. For details, see the chapter Applying Upgrade Packs and Database Upgrade Scripts.
4. Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.

Upgrading from versions 3.5.x-4.4.x

If the version of X-Cart on which your current store is based is earlier than 4.5.0, the upgrade procedure is more complex. To upgrade your store to 4.5.x, you might need to go through a series of transitional upgrades. At least one of the upgrades will be a branch-to-branch upgrade, which means that you will be able to upgrade your database, but X-Cart software will have to be installed from scratch from the 4.5.x distribution package. To upgrade your store, follow these steps:

1. Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
2. Retrieve the value of the variable $blowfish_key from the file config.php in the root directory of your existing X-Cart installation and temporarily save it somewhere on your local computer.
   You will be asked to provide the Blowfish key later on to allow X-Cart to decrypt the data in the upgraded database.
3. Obtain the upgrade pack(s) needed to bring your store to one of the versions for which a direct database upgrade to 4.5.x is provided (4.1.12, 4.2.3, 4.3.2 or 4.4.5).
   For instructions on obtaining upgrade packs, see Obtaining upgrade packs and database upgrade scripts.
4. Apply the upgrade pack(s) to your X-Cart installation. For instructions, see Applying upgrade packs and database upgrade scripts. As a result, the version of your store should now be one of the following: 4.1.12, 4.2.3, 4.3.2 or 4.4.5.
5. Back up your store's database.
6. Obtain a database upgrade script to bring your store's database from the current version (4.1.12, 4.2.3, 4.3.2 or 4.4.5) to 4.5.0. See Obtaining database upgrade scripts.
7. Apply the database upgrade script. For instructions, see Applying database upgrade scripts. As a result, the structure of your store's database should now correspond to that of X-Cart version 4.5.0.
8. Install a fresh copy of X-Cart 4.5.0 as described in the section X-Cart:Installation.
   When installing X-Cart:
   • If you are installing X-Cart to the directory on your server or hosting account where your current X-Cart store is located, at the first step of the installation wizard select the radio button 'New Installation' and enter the Auth code for the existing X-Cart installation. If you do not remember the code, retrieve the value of the variable $installation_auth_code from the file <xcart_dir>/include/install.php.
   • At the step 'Preparing to Install X-Cart Database' of the installation wizard, select the check box 'Update config.php only' and enter the Blowfish key for the upgraded database.
9. Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.