How to install one of my Zen Cart mods

This page is a rookie's guide to installing one of my mods. Many (although not all) other people package their mods the way I do, so this may also be useful if you're installing someone else's mods.

Note: These instructions only deal with the mechanics of copying files to your cart. There may be many more instructions you need to follow for any particular mod. Please see the mod's help pages for details.


If you installed your Zen Cart using Fantastico or perhaps had a friend or subcontractor install it for you, installing a mod might seem daunting. Don't worry - there's nothing to it as long as you follow some basic principles.

Reading the instructions

This page shows you how to copy files into your cart. This is just one part of installation; there may be many associated tasks that need to be done. All my contributions come with a README file; please take the time to review it to get the whole picture of how installation is to be done.

Reading the instructions before starting installation is a great way to reduce grief. In addition to the README file, many of my contributions have their own web page where I answer frequently asked questions.

Getting Started

Before you start, you'll need to verify that you have some things.
  • My mods are provided in zip format, so you'll need a tool to unzip the file.
  • You'll need a tool to transfer the files from your local PC to your webserver.
  • You'll need a simple text editor to do customizations to files

Zip File Structure

Here's the complete structure of the Quantity Discounts contribution as of version 1.09:

There are only two code files here and one README; the other things you see are parent directories for those files. An abbreviated listing of this is

The hierarchy of these files is intended to exactly duplicate the structure of your cart. So if your cart is installed on your webserver under (say) /public_html/zencart, then to install the file ./includes/modules/order_total/ot_quantity_discount.php you would ftp to your site, change directory to public_html, then to zencart, then to includes, then modules, then order_total, and transfer the file ot_quantity_discount.php to that directory.

If your cart is under (say) /httpdocs/public_html/, the instructions would be the same; cd to this location, then down into includes/modules/order_total and copy the file in.

So in fact, to install this contribution, all you have to do is copy these two files into your cart, turn on the Quantity Discounts order total module (under Admin->Modules->Order Totals), and you're done.

Templates and Core Files

I chose the example of Quantity Discounts because it's the simplest form of a mod - it contains only new, original files. What about something more complex which modifies existing files in the cart?

Zen Cart has two facilities for dealing with situations like this, and you need to understand them prior to installing mods to save yourself grief the next time you upgrade your cart.

Since changing the "skin" or "theme" of the cart is the most common customization, the user interface is built to accommodate relatively easy customization. Zen Cart calls this mechanism "template overrides" and provides guidelines on how to create a custom template. In my mods, I assume the template name is "custom." So if you see a file with the name "custom" as part of its name, you know it's a template component. If you've used a name other than "custom" then you will have to move the file accordingly. Note: If you are using Zen Cart 1.5.5 or higher, your template name will be "responsive_classic" if you have not changed it.

Some examples: the Better Together Promotional Page contains a file called
If your template name is "scott", you would install this file in

Discount Preview contains a file called
If your template name is "apple", you would install this file in

Not all files can be handled by the template system. For instance, files in includes/modules/pages cannot be overridden. My recommendation for files like this is that during the installation process, you make a backup of the original file, and name it <original-filename>.orig. For instance, my Gift Wrap at Checkout contribution modifies the file ./admin/invoice.php . Prior to installation, rename this file ./admin/invoice.php.orig This serves two purposes:
  • In the event of a problem, you can easily restore the original file
  • When it comes time to upgrade your cart, you can easily identify the core files you've changed by searching for files named *.orig
Note that ".orig" should be a suffix onto the original filename. (Don't name the file invoice_orig.php or orig_invoice.php.)

Database Changes

Some mods require database changes. For instance, Gift Wrap at Checkout includes a file called orders_wrap.sql, which modifies your database.

These files are best run through the Zen Cart admin panel, which will take care of the prefix (if you have one). To do this, go to Admin->Tools->Install SQL patches.

Alternately, you can run them using phpMyAdmin, but you will need to edit the .sql script to account for the prefix. errors occur during execution. Ask your host if you're not sure how to run this tool.

For instance, if the file creates a table called "orders_giftwrap"
CREATE TABLE orders_giftwrap(

you will need to change this to reflect your prefix, i.e.
CREATE TABLE zen_orders_giftwrap(
assuming your prefix is "zen_".

If you have used a prefix, it is stored in includes/configure.php; look for the variable DB_PREFIX.

If you do an install and get an error like
1146 Table 'yourdb.zen_better_together_admin' doesn't exist
[SELECT * FROM zen_better_together_admin ORDER BY id DESC ]
If you were entering information, press the BACK button in your browser and re-check the information you had entered to be sure you left no blank fields.
This means you used phpMyAdmin but forgot to edit the .sql file to include your prefix.

The most important principle to remember when changing your database is that you must do a backup prior to making the change. You can do a backup using phpMyAdmin.

Not all database modifications will be done through a .sql file; for instance, any file which requires you to click an "Install" link from Admin->Modules is modifying your database. Be sure to make a backup!

Some mods use the "TYPE=MyISAM" syntax when doing a CREATE TABLE, which is not accepted by some newer versions of MySQL. If you get a message like this when running an SQL script:
ERROR 1064 (42000): You have an error in your SQL syntax; check the manual that
corresponds to your MySQL server version for the right syntax to use near 'TYPE=MyISAM'
at line 1

To fix this, simply edit the .sql file and change all instances of


The best way to upload is to upload the ENTIRE includes directory from the unzipped file onto your includes directory, and the ENTIRE admin directory (if one exists) from the unzipped file onto your admin directory (after the appropriate renames):
  • If your admin folder is named ABCDEF, rename the admin folder in the unzipped mod to ABCDEF, and upload the entire folder.
  • If the unzipped file contains template specific files, rename the containing directories to the name of your template. For instance, if your template is named "blue" and the mod has a directory named
    rename this to
    Similarly, if the mod contains a directory called
    rename this to

Example 1: Quantity Discounts

In this example, we will assume your cart is installed under public_html on your webserver
  • Upload the includes directory to your includes directory.

If you're doing it file by file (not recommended)
  • Copy ./includes/languages/english/modules/order_total/ot_quantity_discount.php to
  • Copy ./includes/modules/order_total/ot_quantity_discount.php to

Example 2: Better Together

In this example, we will assume your cart is installed under httpdocs/testsite on your webserver, and that your template is named "brownie."

  • In the unzipped file, rename ./includes/templates/custom to includes/templates/brownie
  • Upload the includes directory in the unzipped file to your httpdocs/testsite/includes directory.

If you're doing it file by file (not recommended)
  • Copy ./includes/languages/english/modules/order_total/ot_better_together.php to
  • Copy ./includes/modules/order_total/ot_better_together.php to
  • Copy ./includes/templates/custom/templates/tpl_better_together_marketing.php to
  • Copy ./includes/templates/custom/templates/tpl_better_together_marketing_images.php to
  • Copy ./includes/templates/custom/templates/tpl_better_together_xsells.php to
  • Copy ./includes/templates/custom/css/stylesheet_bettertogether_product.css to

Figuring out ID values

Most of my mods use IDs: category ids, product ids, manufacturer ids, etc. How do you know what values to use.

It's really pretty easy. The first thing you need to do is turn off any SEO URL mod you have so you can see regular Zen Cart URLs, which contain a lot of information.
  • Product ID: This is the easiest one. When you go to the product info page for a product in your cart, the URL will look like this:
    The number after "products_id=" is the product id (173 in this case).
  • Category ID: This term has different meanings depending on the context; look at my Category Issues page.
  • Manufacturer ID: See Manufacturers in Zen Cart.

Common Problems

  1. Blank Page: If you get a blank page after an install, you can debug it by following the blank page help.
    1. Not all blank page problems show up as a complete blank page! If you look at the bottom of your screen and see that the footer is missing, you have the blank page problem.
    2. If you have the blank page problem, but don't see error files in your cache directory, your permissions may not permit the webserver to write into the directory.

      You can test this by editing includes/functions/functions_email.php and removing the first line (which is "<?php"). Refresh the browser page in which your are viewing your cart or admin, and check the cache directory. You should see an error file; if you don't, your permissions are too strict. Note that you may need to use your CPanel File Manager to fix them; not all systems allow ftp to set permissions. Remember to restore includes/functions/functions_email.php!
  2. PHP issues which don't generate blank pages: Even if you don't see a blank page or a partially blank page, you could still have PHP interpretation issues. Look in the cache directory for error files. See the blank page help referenced above for details.
  3. File Transfer issues: Check the files you have transferred and ensure they are the same size as the ones on your host computer. Do not use SmartFTP, CuteFTP or browser based FTP. Do not use DreamWeaver's FTP. Use a proper FTP client such as FileZilla or Coffee Cup FTP.
  4. Renaming files incorrectly: This can sometimes lead to a blank page situation. There's an easy trick to it: when creating a backup file, just remember not to use the extension ".php" for php files. For example, if you are backing up
    try backing it up to one of these names:
    DO NOT call it something like
    includes/functions/old_functions_prices.php   // NO!!! DO NOT DO THIS! 
  5. Failed merges: Backup your files, then take my zip file, rename the template directories as explained above, and transfer the files as is with no more changes to your site. See if you still have the same problem. (In all likelihood you won't.) If you don't, you have merged your changes and my changes incorrectly. Introduce your changes back one at a time, and see where it breaks.
  6. Many of my mods that require a setup() function (Better Together, Combination Discounts, Big Chooser, Big Spender, Table Discounts, etc.) Some people try deleting the setup function and wind up deleting the final brace in the file, which causes a blank page on checkout. The bottom of the file includes/modules/order_total/the-mod-name.php should look like this:
       function setup() { 
          .. some statements here ....
    The final curly brace must not be deleted.
Still having problems? I will install most of my mods for a fee (generally $60). Click the PayPal button below.

Don't want to hire me? The person I recommend most often is Delia Lunsford. Hire her if you want, especially if it's not one of my mods.