Documentation Home

# Welcome to Zen Cart®

Dear Zen Cart® User,

Zen Cart® is made available to you for your use, addition, changes, modification, etc. without charge, under Version 2 of the GNU General Public License.

While we do not charge for this software, donations are greatly appreciated, each time you install a new version, to help cover the expenses of maintenance, upgrades, updates, the free support forum and the continued development of this software for your online E-Commerce store.

Donations can be made on the Zen Cart® Team Page

We appreciate your support.
The Zen Cart® Team

# Zen Cart® Requirements

- For up-to-date requirements, see: Zen Cart® Server Requirements
- Apache must be configured with AllowOverride set to either "All" or at least both "Limit" and "Indexes" parameters, and preferably the "Options" parameter as well.
- PHP must be configured to support CURL with OpenSSL

While Zen Cart® can run on Windows/IIS servers, Linux/Apache servers are recommended for best results.

# Before You Start

## Getting Started

This is a basic guide to upgrading Zen Cart®. If you have not yet installed Zen Cart, please see the 1.readme_installation.html file for installation instructions.

To upgrade Zen Cart®, you will need the same basic tools you used to install and customize it in the first place:
- An FTP program
- A text editor friendly to HTML/PHP code
- phpMyAdmin or equivalent access to your MySQL database
- Your Control Panel for managing your webspace

Additionally, you will find that a file comparison tool such as WinMerge, Beyond Compare or ExamDiff (Linux) to be very helpful. (There is also BBedit for the Mac.)

## Online Documentation

You can find the lastest upgrade instructions, and alternate ways of upgrading, by visiting: www.zen-cart.com/upgrade.

## Payment and Shipping Modules

You will need to re-install all your active payment and shipping modules as part of your upgrade:

- BEFORE UPGRADING, Take note of the login IDs, transaction keys, email addresses and other settings already configured in EACH of your Payment and Shipping modules.
  - You will need this information so you can re-enter it after re-installing the modules.
- Remove each module by clicking the "Remove" button for each one.
- AFTER UPGRADING, Install each module (that you are using) in Admin->Modules->Payment and Admin->Modules->Shipping in order to take advantage of the bugfixes and feature improvements in each module.
  1. You do NOT need to do this with modules you are NOT using.
  2. If you are no longer using a certain module anymore and it does not have a red dot next to it, click the "Remove" button to save on processing performance.
- Re-enter all your configuration settings for each module as you go along.
  - BE SURE TO TEST each one before you take your store live again, to make sure you've got all your settings entered correctly.

^^ Back to Top ^^

# The 3-Step Zen Cart® Upgrade

## Introduction

Upgrading follows three easy steps. Take your time going through each stage carefully and methodically.

Do not rush the process and always ensure you made backups before you attempt an upgrade.

Spend time getting familiar with the demo data to become comfortable with new features of the new release.

## Step 1: Zen Cart® Upgrade Preparation

### Backup Current Zen Cart® Installation

- Make a list of any add-ons you have installed, for later reference.
- Create a backup of your current Zen Cart® installation on your Local PC
  1. Perhaps call this folder "zen_backup"
  2. Make a full backup of your database (dump to SQL file). Store this file on your PC for later reference.
  3. Make a full backup of your site files (ftp to your PC and zip it up for safe-keeping).

### Try New Zen Cart® Version

- Download and unzip the latest Zen Cart® version to your Local PC
- Upload this fileset to your website under a "demo" folder
  1. Install this new version into a separate database and include the Demo products.
  2. This is just for a place for you to play with the new version and get used to its new features.
  3. This can be deleted after conversion is complete.
- Study the new features and any documented changes to the template structure as well as the "changelog".
  1. Use the demo products in the demo shop as examples.
  2. See also the supporting documentation provided with the new release.

### Determine Customizations and Edits

- Download and unzip a copy of the Zen Cart® version you originally installed or last upgraded to.
  1. Place in a separate working folder on your Local PC (perhaps "zen_orig").
  2. This should be a "vanilla" version without any changes or modifications.
     - Download a copy from the Zen Cart® Archives.
- Run a tool like WinMerge to compare the files in "zen_orig" against those in "zen_backup" to determine the customization details/differences between your installation and the "vanilla" Zen Cart version.
  1. Make a list of all the files that are "different".
  2. In WinMerge, double-click on each file and note what the differences are.
     - If the differences are just language defines for display text, those will be simple to carry forward.
     - If the differences are actual programming/code differences, you will need to make detailed notes in order to carry over those changes to the new new new version.
- Any mods/add-ons installed may contain programming changes not compatible with a new release.
  1. Your list of add-ons may help you narrow down the source of any differences you find between versions.
  2. You may have to download the add-on again to take a look at the readme or code contained in it.
  3. You may have to contact the author to ask for an updated version.
- As you make a list of changes, you may want to move things into the Zen Cart® template override system
  - See the Zen Cart® site for Template System FAQ.

### Personalize Zen Cart® Upgrade

- Create another copy of the latest Zen Cart® version on your Local PC.
  - Place in a 3rd directory (perhaps "zen_new"), separate from the other two folders compared above.
- Using the list of files you made earlier, go through each "changed" file, and make your changes from the old version into the new version.
  1. Simple language edits will be just a matter of copy-and-paste.
  2. Programming changes to core components will be more difficult and require significant testing.
- You may find WinMerge handy at this stage as well
  1. However, you may find many extra differences that may not be related to your own customizations, or that may conflict.
  2. Be careful making changes to program code.
- There may be several changes to be made to files previously overridden using the template overrides system
- Compare files from /includes/templates/MYTEMPLATE/* to /includes/template/template_default/*.
- Also with language file overrides, sideboxes, etc

## Step 2: Zen Cart® Upgrade Testing

- Make a NEW database to install the new version of Zen Cart® into.
  1. Use your hosting control panel or phpMyAdmin to do this.
  2. If the last backup you made of your data is older than the last order that might have been processed or customer registration, make a fresh database backup.
  3. Restore your database from the backup in Step 1 into the new database just created.
- Edit the "/zen_new/includes/configure.php" file
  1. Ensure that your DATABASE_NAME matches your NEW database.
  2. Also verify database username and password in case that information has changed.
  3. Save this file, and be sure to upload it as part of the next step. Repeat for the /admin/includes/configure.php file as well:
- Upload the files from your modified "new version" (created in Personalize Upgrade) to your server
  1. Place in an alternate folder (perhaps called "/store_new")
  2. Ensure that you have uploaded the "/zen_new/zc_install" folder to your server.
  3. If your /zen_new folder does not have "/includes/configure.php" and "/admin/includes/configure.php" files, copy them from the "zen_backup" folder.
- Navigate to /store_new/zc_install/index.php using your browser
  1. Choose "Database Upgrade" when prompted.
  2. Do not select "Install", or you will overwrite your database.
  3. If "Upgrade" is not offered, then the installer was unable to connect to your database to confirm what version its structure is at.
  4. Check your configure.php settings.
- Install each module in Admin->Modules->Payment and Admin->Modules->Shipping.
  1. You do NOT need to do this with modules you are NOT using.
  2. If you are no longer using a certain module and it does not have a red dot next to it, click the "Remove" button to save on processing performance.
- Test your customizations.
  1. Compare with the test/demo install performed earlier.
  2. Edit as needed.

## Step 3: Zen Cart® Upgrade Execution

- When satisfied that all is OK, go live.
- If significant time has passed since you did your last backup, you may want to repeat the steps in this "Testing" section again, using a fresh backup from your live shop.
  - You do not need to re-upload files again ... simply do the database restore, and run the installer to do the database upgrade again.
- Put your shop into "Down for Maintenance" mode in the admin area.
  - Be sure to add your IP address to the list of allowed addresses to get into the site for previewing.
- Rename the existing Zen Cart® folder (perhaps "store") on your site to "store_old"
- Rename the "store_new" folder to "store"
  - At this point the new version is live.
- Test it to be sure that things are operating as desired.
  - If you have small problems to repair, turn "Down for maintenance" on and off again as necessary.

^^ Back to Top ^^

# Help and Support

For additional help and support, visit the Zen Cart® FAQ and the Zen Cart® Support Forum.

Zen Cart® is derived from: Copyright 2003 osCommerce
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE
and is redistributable under Version 2 of the GNU General Public License.

This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.

Copyright 2003 - 2018 Zen Ventures, LLC
Zen Cart®
www.zen-cart.com