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 X-Cart Account.
The information below will hopefully give you a better understanding of X-Cart upgrades.
Contents
Video tutorial
This tutorial is courtesy of Mike White. It provides instructions on taking a store from 4.4.5 to 4.6.3. The steps taken should cover most everything you will encounter while upgrading X-Cart 4 (Classic).
General information on upgrading
Understanding the 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 are upgrading to a later minor version within the same branch or to a later major version (different branch).
Upgrading to a later minor version
When you need to upgrade the store to a later minor version within the same 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: 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 Getting Help).
Upgrading to a later major version (branch)
When you need to upgrade your store to a later major version (for example, from X-Cart 4.2.x to X-Cart 4.3.x), the available upgrade options depend on the versions involved. For some versions, we can provide packs for a direct full upgrade. For example, we can provide the following upgrade packs:
- 4.5.х -> 4.6.0
- 4.6.х -> 4.7.0
- 4.6.х -> 4.7.1
For other versions, there are no ready-made full upgrade packs, and for such versions, it is only possible to upgrade the store database, connecting the database to a fresh X-Cart installation.
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.
The set of available database 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.13.5.12 X-Cart Branch 4.0.x
* 4.0.63.5.14 X-Cart Branch 4.0.x
* 4.0.12
X-Cart Branch 4.1.x
* 4.1.11
* 4.1.124.0.19 X-Cart Branch 4.1.x
* 4.1.11
* 4.1.124.1.11 X-Cart Branch 4.2.x
* 4.2.04.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.04.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.04.3.2 X-Cart Branch 4.4.x
* 4.4.0
X-Cart Branch 4.5.x
* 4.5.04.4.5 X-Cart Branch 4.5.x
* 4.5.0
In the situation where 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.
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 with 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 the custom code and design after the upgrade, which requires adequate experience in PHP, HTML and MySQL. So, if you are using 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.7.x step by step
Upgrading from version 4.7.0 or later
If the version of X-Cart on which your current store is based is 4.7.0 or later, to upgrade your store to a newer minor version within the 4.7.x branch (for example to version 4.7.5) you will need to follow these steps:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Obtain an upgrade pack for the direct upgrade from your current version to the desired version. For details, see the chapter Obtaining in-branch upgrade packs.
- Apply the upgrade pack to your X-Cart installation. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
Upgrading from versions 4.5.0-4.6.x
If the version of X-Cart on which your current store is based is 4.5.0-4.6.x, you have two options:
- to upgrade your entire store (both the software and the database) to 4.7.x;
- to upgrade just your store's database to 4.7.x and install the X-Cart software anew.
If you choose the first option (to upgrade both the software and the database), you will need to use our upgrade packs. Note that if there is not a direct upgrade pack to bring your store to the desired version, you will need to go through one or more transitional upgrades. To complete the upgrade:
- In your development environment, create a copy of your existing store. For details, see the chapter Before the upgrade.
- Obtain the upgrade pack(s) needed for upgrade from your current version to the desired version. If there are more than one upgrade packs, apply them consecutively, one pack at a time.
For instructions on obtaining upgrade packs, see Obtaining upgrade packs and database upgrade scripts. - Apply the upgrade pack(s) to your X-Cart installation. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
If you choose the second option (to upgrade just the database), you will need to follow these steps:
- In your development environment, create a copy of your existing store. For details, see the chapter Before the upgrade.
- Retrieve the value of the variable $blowfish_key from the file <xcart_dir>/config.php of the development copy of your store and temporarily save it somewhere on your local computer. Also take note of the following values:
- $xc_security_key_session
- $xc_security_key_config
- $xc_security_key_general
You will need them later.
- In the File Area section of your X-Cart Account, obtain an X-Cart distribution package of the same version as the version from which you are upgrading. For example, if you need to upgrade from 4.6.2 to 4.7.5, get a distribution package for X-Cart 4.6.2. In your development environment, install a fresh copy of X-Cart from this distribution package pointing it to the database of the development store copy you created at Step 1. To do so, during the installation process, provide to the installation wizard the database connection details of the development store copy you created at Step 1, enable the option "Update config.php only" and enter the Blowfish key value you saved at Step 2.
- Obtain the upgrade pack(s) needed to bring your store to the desired version. For example, if you need to upgrade from 4.6.2 to 4.7.5, there is not a direct upgrade pack that would allow you to upgrade from 4.6.2 to 4.7.5, so you will need to download two upgrade packs: 4.6.2->4.7.2 and 4.7.2->4.7.5.
For instructions on obtaining upgrade packs, see Obtaining upgrade packs and database upgrade scripts. - (This step is needed for X-Cart versions 4.5.5-4.7.x) After installing X-Cart with the option "Update config.php only" enabled, before logging in to the installed store as admin, be sure to replace the following values in the file <xcart_dir>/config.php:
- $xc_security_key_session
- $xc_security_key_config
- $xc_security_key_general
with the values from your previous installation (The ones you have taken note of at Step 2).
- Apply the obtained upgrade pack(s) to your development store copy (If there are more than one upgrade packs, apply them consecutively, one pack at a time. For example, first apply the pack to bring the store version from 4.6.2 to 4.7.2, then apply the pack to bring the store version from 4.7.2 to 4.7.5. For instructions on the application of upgrade packs, see Applying upgrade packs and database upgrade scripts.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
Upgrading from versions 3.5.x-4.4.5
If the version of X-Cart on which your current store is based is earlier than 4.5.0, to upgrade your store to 4.6.x, you will need to go through a series of transitional upgrades. Note that you will be able to upgrade only your database, but X-Cart software will have to be installed from scratch from the distribution package. To upgrade your store, follow these steps:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Retrieve the value of the variable $blowfish_key from the file <xcart_dir>/config.php 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. - 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. - Apply the upgrade pack(s) to your development 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.
- Back up your store's database.
- 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.
- 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.
- Install a fresh copy of X-Cart 4.5.0 in a new (empty) folder using the connection details of the upgraded database (MySQL database name, MySQL user name and MySQL password) (see also X-Cart:Installation).IMPORTANT: 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 (the one that was retrieved earlier at step 2).
- Obtain the upgrade pack(s) needed to bring the store from 4.5.0 to the desired version within the 4.7.x branch. You may need more than one upgrade packs.
- Apply the upgrade packs. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
Upgrading to X-Cart 4.6.x step by step
Upgrading from version 4.6.0 or later
If the version of X-Cart on which your current store is based is 4.6.0 or later, to upgrade your store to a newer minor version within the 4.6.x branch (for example, from version 4.6.0 to version 4.6.1) you will need to follow these steps:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Obtain the upgrade pack(s) for the direct upgrade from your current version to the desired version. For details, see the chapter Obtaining in-branch upgrade packs.
- Apply the upgrade pack to your X-Cart installation. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
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-4.5.x, you have two options:
- to upgrade your entire store (both the software and the database) to 4.6.x;
- to upgrade just your store's database to 4.7.x and install the X-Cart software anew.
If you choose the first option (to upgrade both the software and the database), you will need to use our upgrade packs. Note that if there is not a direct upgrade pack to bring your store to the desired version, you will need to go through one or more transitional upgrades. To complete the upgrade:
- In your development environment, create a copy of your existing store. For details, see the chapter Before the upgrade.
- Obtain the upgrade pack(s) needed for upgrade from your current version to the desired version. If there are more than one upgrade packs, apply them consecutively, one pack at a time.
For instructions on obtaining upgrade packs, see Obtaining upgrade packs and database upgrade scripts. - Apply the upgrade pack(s) to your X-Cart installation. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
If you choose the second option (to upgrade just the database), you will need to follow these steps:
- In your development environment, create a copy of your existing store. For details, see the chapter Before the upgrade.
- Retrieve the value of the variable $blowfish_key from the file <xcart_dir>/config.php of the development copy of your store and temporarily save it somewhere on your local computer. Also take note of the following values:
- $xc_security_key_session
- $xc_security_key_config
- $xc_security_key_general
You will need them later.
- In the File Area section of your X-Cart Account, obtain an X-Cart distribution package of the same version as the version from which you are upgrading. For example, if you need to upgrade from 4.5.2 to 4.6.1, get a distribution package for X-Cart 4.5.2. In your development environment, install a fresh copy of X-Cart from this distribution package pointing it to the database of the development store copy you created at Step 1. To do so, during the installation process, provide to the installation wizard the database connection details of the development store copy you created at Step 1, enable the option "Update config.php only" and enter the Blowfish key value you saved at Step 2.
- Obtain the upgrade pack(s) needed to bring your store to the desired version. For example, if you need to upgrade from 4.5.2 to 4.6.1, there is not a direct upgrade pack that would allow you to upgrade from 4.5.2 to 4.6.1., so you will need to download two upgrade packs: 4.5.2->4.6.0 and 4.6.0->4.6.1.
For instructions on obtaining upgrade packs, see Obtaining upgrade packs and database upgrade scripts. - (This step is needed for X-Cart versions 4.5.5 and later) After installing X-Cart with the option "Update config.php only" enabled, before logging in to the installed store as admin, be sure to replace the following values in the file <xcart_dir>/config.php:
- $xc_security_key_session
- $xc_security_key_config
- $xc_security_key_general
with the values from your previous installation (The ones you have taken note of at Step 2).
- Apply the obtained upgrade pack(s) to your development store copy (If there are more than one upgrade packs, apply them consecutively, one pack at a time. For example, first apply the pack to bring the store version from 4.5.2 to 4.6.0, then apply the pack to bring the store version from 4.6.0 to 4.6.1. For instructions on the application of upgrade packs, see Applying upgrade packs and database upgrade scripts.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
Upgrading from versions 3.5.x-4.4.5
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.6.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 distribution package. To upgrade your store, follow these steps:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Retrieve the value of the variable $blowfish_key from the file <xcart_dir>/config.php 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. - 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. - Apply the upgrade pack(s) to your development 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.
- Back up your store's database.
- 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.
- 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.
- Install a fresh copy of X-Cart 4.5.0 in a new (empty) folder using the connection details of the upgraded database (MySQL database name, MySQL user name and MySQL password) (see also X-Cart:Installation).IMPORTANT: 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 (the one that was retrieved earlier at step 2).
- Obtain the upgrade pack(s) needed to bring the store to the desired version within the 4.6.x branch. If there is not a pack for a direct upgrade, you may need to obtain more than one upgrade packs.
- Apply the upgrade packs. For details, see the chapter Applying Upgrade Packs.
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
Upgrading to X-Cart 4.5.x step by step
Upgrading from version 4.5.0 or later
- from 4.4.1 to 4.4.5
- from 4.3.0 to 4.4.5
- from 3.5.0 to 4.1.12
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 newer minor version within the 4.5.x branch (for example to version 4.5.5) you will need to follow these steps:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Obtain an upgrade pack for the direct upgrade from your current version to the desired version. For details, see the chapter Obtaining in-branch upgrade packs.
- Apply the upgrade pack to your X-Cart installation. For details, see the chapter Applying Upgrade Packs.
- 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:
- Consider the environment and make a development copy of your store. For details, see the chapter Before the upgrade.
- Retrieve the value of the variable $blowfish_key from the file <xcart_dir>/config.php 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. - 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. - Apply the upgrade pack(s) to your development 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.
- Back up your store's database.
- 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.
- 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.
- Install a fresh copy of X-Cart 4.5.0 in a new (empty) folder using the upgraded database's credentials (MySQL database name, MySQL user name and MySQL password) (see also X-Cart:Installation).IMPORTANT: 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 (the one that was retrieved earlier at step 2).
- Complete the required post-upgrade tasks. For details, see the chapter After the upgrade.
See also:
