About PHP versions

Zen Cart® v1.5.5 is designed for PHP 5.6 to 7.1, with MySQL 5.1 thru 5.7 and Apache 2.2/2.4

It is compatible with PHP 5.2.10 through PHP 7.1, for backward-compatibility while upgrading your site, but you should be using a newer version whenever possible. As of the time of writing this, PHP 5.6 is considered obsolete. and you should be using PHP 7.1 or greater.

Upgrade Instructions

This document only mentions the actual changes specific to v1.5.5 since v1.5.4.

From v1.5.4

If you are already using v1.5.4 and *have NOT customized or altered* any of the files listed in the changed_files-v1-5-5.html document, then simply replace those files with the new files as listed.

If you *have customized or altered* certain files, simply re-do your customizations in the new version of those particular files by making the same changes needed.

If you are using Addons/Plugins that have made alterations to those files, it is best to compare those changed files against the original Zen Cart files for the version those plugins were built for, and see what changes were there ... and then re-build those changes in the v1.5.5 file.

To v1.5.5 from v1.5.3 or older

If you are upgrading from a version OLDER than v1.5.4, then please do a standard site upgrade.

Be sure to review all the links in this article, including tips on staging the upgrade in a separate directory/folder.

CHANGELOG - List of Changed Files

For a list of files that have been changed since v1.5.4, see the changed_files-v1-5-5.html document.

Important Note About configure.php Files

The contents of configure.php have been simplified ... and they are MUCH SMALLER now!

The dist-configure.php shows the simplified contents, and zc_install will generate the leaner files (when doing fresh installs).

Also, zc_install will upgrade your configure.php files to the new format as long as the files are writable by your server's PHP.

A Note About the New Template

While Zen Cart® v1.5.5 contains a newer "responsive_classic" template, we STRONGLY recommend that upgraders first upgrade the site using everything (including template_default) EXCEPT the contents of responsive_classic template.

Then once the upgraded site is working properly you can consider what changes you might want to make to your own active template.

(Important notes about template_default are shown below)

AGAIN: The responsive_classic template should NOT be implemented immediately as part of an upgrade; it should be a separate step ... if it is even used at all.

It is not NECESSARY to use responsive_classic ON YOUR EXISTING SITE, and you should UPGRADE THE REST OF YOUR SITE FIRST before attempting to convert/adapt it for use.

Notes About Changes to template_default

Upgrading Notes

Upgraders should ensure they update *BOTH* template_default *AND* your custom template as described here:

In Zen Cart the template_default directory contains the master copy of all storefront page templates.

The normal procedure for customizing template files for use in your own personalized template is to make a copy of the corresponding file from template_default, put it into your own template folder (and matching folder structure), and make your customizations in that copy of the file.

This way the only files you need in your personalized template folder are those that you have altered in some way from template_default.

With that explained, it is important that whenever you upgrade your site, you should also inspect ALL the template_default files to determine which changes in those files need to be replicated in your customized files.

Often a tool like Beyond Compare or Araxis Merge or GnuDiff can be helpful for this.

The process is simple: compare the template_default directory files from your *old* version against the template_default files in the *new* version, and use those results as a reference to copy those updated changes into each of the files you have customized in your custom/personalized template in your store.

Then, and only after you have done all those comparisons and updated your customized files in your custom template folder, you will copy the template_default files from the new version into the template_default directory of your store. This way you will be left with updated personalized files *and* updated template_default files.

Changes in template_default for v1.5.5

The template_default files previously had a lot of old <table> markup to specify widths, cell borders and padding and spacing.

These have been removed in v1.5.5 and relevant styles added to the bottom of the main stylesheet.css file.

You will want to add the updated CSS parts to your own stylesheet if your custom template still uses those tables. (A few 3rd-party templates have aggressively ripped out various tables and may not be affected by this change.)

A few CSS changes were made in template_default to change IDs of repeating elements to be classes instead. Of note, "#cartDisplay" is now ".cartDisplay", and "#cartImage" is now ".cartImage".

What's New...

Changes from v1.5.5e to v1.5.5f

Since the release of v1.5.5e on 6-March-2017, the following changes have been applied to become v1.5.5f ...

• All known v1.5.5 bugfixes and security fixes are included in v1.5.5f
• Checkout - As a help to people getting PayPal TLS notifications, the CURL Testing tool now reports compatibility with tlstest.paypal.com
• Checkout - Square Payments support is now built-in. Start taking credit card payments in just 5 minutes! See www.zen-cart.com/partners/square_setup
• Checkout - FirstData soft-descriptors now optional via module settings
• Checkout - PayPal - Australia settings explained better in configuration screen
• Checkout - PayPal IPN-handler posts back over ipnpb URL and now gracefully ignores unrecognized new notification types
• Checkout - Payeezy module now accommodates 2-series MC BINs
• Checkout - Internal fix to payment modules to avoid thousands-rounding errors
• Checkout - Authorize.net AIM - add option to display reason for CVV or date failure
• Checkout - Authorize.net AIM - improvements to detect always-SSL site configuration
• Checkout - Credit Card Slamming threshold now customizable via Observer code or plugin
• Fix upload-class bug related to filtering desired file-extensions
• Fix multi-language error (since v155a) in functions_email for PHPMailer
• Fix possible bug in subdomain handling of secure cookie session handling
• Fix attribute sort-order rules
• Admin: Fix percent calculators on Products Price Manager
• Admin: Fix a few sanitizer fields to avoid over-cleaning
• Admin: Update currency-exchange calculators since BOC changed formats
• Template - The new/featured/all pages submit over SSL to avoid mixed-content alerts
• Template - Improvements for jQuery conflict prevention, and support older browsers
• Template - Compatibility updates to accommodate OnePageCheckout plugin integration
• Template - Support ISO-8601 style date-of-birth date
• Template - Fix CSS typo in colors
• Template - hreflang URL correction
• Template - Fix incorrect use of logo image height
• Fixed - if an invalid or non-existent tax rate was encountered, would get: PHP Warning: A non-numeric value encountered in /includes/functions/functions_taxes.php on line 172
• Security: CVE-2017-11675 - Low-Risk vulnerability (required your Admin login to be hijacked first). Now prevents exporting to invalid filenames.
• Optimization - Abort ajax requests from spiders
• Enhancement - Cache-bypass added for certain db queries, so retrieved data is always fresh
• Enhancement - Uploading now gives more detailed feedback about failures related to invalid file types.
• Utility - Plugin version-check utility optimized to allow specific version-comparisons, and adapt to timeouts more quickly.
• Internal - Upgrade PHPMailer from 5.2.22 to 5.2.26
• Internal - Upgraded MobileDetect from 2.8.17 to 2.8.30
• CKEditor integration fixes


• No database updates necessary

Changes from v1.5.5d to v1.5.5e

Since the release of v1.5.5d on 31-Dec-2016, the following changes have been applied to become v1.5.5e ...

• Upgrade PHPMailer from 5.2.21 to 5.2.22
• Update gmail support to use TLS per published standards
• Fix bug introduced in v1.5.5c related to deleting customers
• Add built-in support for new .htaccess rules required for Apache 2.4, so mod_compat doesn't need to be installed
• zc_install improvements better handling for upgrades from v138 / v139
• zc_install - removed extraneous backticks from upgrade SQL from v154-to-v155
• Bridge compatibility for transition to removal of the ENABLE_SSL_ADMIN constant
• Consolidate to a single upload class, shared between admin/catalog
• Updates to Payeezy and First Data HCO payment modules
• Revert null-exception change until further notice

Changes from v1.5.5c to v1.5.5d

Since the release of v1.5.5c on 26-Dec-2016, the following changes have been applied to become v1.5.5d ...

• Upgrade PHPMailer from 5.2.19 to 5.2.21 to fix critical security bug CVE-2016-10045
• Update Authorize.net storage field type in database to accommodate different values returned by Authnet emulator gateways using these modules
• Fix zc_install to prevent DB_CHARSET from being set to blank during upgrades when upgrading v1.3.x configure.php files to new format
• Revert null-exception change until further notice

Changes from v1.5.5b to v1.5.5c

Since the release of v1.5.5b on 2-Nov-2016, the following changes have been applied to become v1.5.5c ...

• Fix serious PHPMailer bug (upgraded to 5.2.19)
• Fix some variable strict-type rule enforcement issues for better PHP 7 compatibility
• Fix sanitizer (admin) overzealous cleaning for Attribute Option Comments
• Fixed bug preventing sending Coupon and GV emails to "all customers"
• Fixed rarely-triggered bug with product-type overrides for delete/copy logic
• Fixed problem where deleting a customer wouldn't delete old product-notification requests associated with that customer
• Fixed PayPal Standard to no longer transmit a comma as thousands-separator. (PayPal is being more strict about this in 2017.)
• Fixed shopping-basket quantity alert problem where changing quantities didn't always fire if min/mix rules were set
• Make null-exception treatment consistent in admin to match catalog

Changes from v1.5.5a to v1.5.5b

Since the release of v1.5.5a on 5-May-2016, the following changes have been applied to become v1.5.5b ...

• Fix Chrome browser javascript incompatibility
• Several fixes to the Admin Sanitizer rules, to stop translating special characters to html entities unexpectedly
• Fix some HTML markup "strict" errors, and CSS alignments in various admin pages
• Relocate shipping-calculation logic in checkout page, to be consistent with other checkout calculations and prevent some shipping rate errors
• Template fix to Responsive Classic to change postal-code to no longer be numeric-only
• Change authorize.net module to use Akamai servers
• Fix Payeezy payment module tokenization problem, and fix sandbox mode problem
• Fix some javascript on checkout pages related to form submission
• Fix out-of-stock alert inconsistency
• Trigger E_USER_ERROR when wrong bindVars rule set
• Update gv_faq language file with community contributions
• Change use of PHP_SELF to SCRIPT_NAME for consistency and to avoid legacy-related problems
• Fix false-positives in error-reporting logic
• Fix leftover indirection variables for PHP7 compatibility
• Fixes to AJAX handlers: reject fake requests; persist session data more effectively
• Change CKEditor trigger to use jQuery CDN instead of Google CDN, for broader global access
• Upgrade PHPMailer to accommodate broader TLS compatibility
• Accommodate MasterCard's recent BIN 2 addition
• Include responsive-classic template layout-boxes in upgrades, even if not using it, for sake of cloning simplicity
• Template fix: fax field was showing even if disabled
• Template fix: fix "back" button on address-book edit screens during checkout
• Multilanguage: make hreflang tag appear for all languages, instead of only for "other than current" language
• Fix admin link to whois resource
• Fix checkout_shipping: No method chosen after cart goes from virtual to mixed
• Handle mysql strict typing issue with legacy PayPal IPN insert
• Fix Free Shipping tax calculation with ot_coupon
• Added extra functions to shopping cart for extracting in-cart weight, price, item details for categories

Changes from v1.5.5 to v1.5.5a

Since the first iteration of v1.5.5 on 17-March-2016, the following changes have been applied to become v1.5.5a ...

• Fix several upgrade-related problems caused by zero-dates in the customers table data/history
• Revamp admin sanitization code to work better with various plugins such as Edit Orders, etc
• Admin orders page had some incorrect CSS classes specified
• Admin customers page had some incorrect HTML tags for span and bold markup
• Admin "Support" link restored to navigation menu
• Admin - fix privilege escalation vulnerability
• Fix missing SEARCH_DEFAULT_TEXT, ERROR_GV_CREATE_ACCOUNT and TEXT_PRICED_BY_ATTRIBUTES language defines
• The zc_install test for availability of SSL and .htaccess could fail due to timeouts when offline
• The zc_install "configure.php file update" was not always handling conversion of old SSL URLs properly
• Fix "uninitialized string offset" error in zen_random_name()
• Fix sort-order of shipping/payment modules when sort-orders are multiple digits
• Responsive Classic: Fix alignment/display of State Dropdown element on address pages
• Fix to inability to choose from address-book during checkout, and fix double "continue" buttons on same page
• Order comments flag was showing incorrectly on PayPal EC transactions
• Restore define for DIR_WS_HTTPS_ADMIN for legacy plugin purposes
• Added several .gitignore files in various folders, to help site developers avoid committing unnecessary files to version control
• For language-specific currency overrides, fix the default
• Fix bindvars to honor string entries that contain 'null'
• add safety to fmod_round
• Fix extra breadcrumb that was appearing when always-open-with-category is enabled
• Update BOC currency parsing to cope with their data changes and division-by-zero errors as a result
• Fix a test-mode bug in Authorizenet AIM module

Changes from v1.5.4 to v1.5.5

The most notable improvements and bugfixes in v1.5.5 since v1.5.4 include:

• All known v1.5.4 bugfixes and security fixes are included in v1.5.5, including tighter control around XSS as well as clickjacking
• Template: The default out-of-the-box template (called "Responsive Classic") is now a mobile-friendly responsive-design theme built for flexibility with tablets, mobile devices, and desktops.
• Template: The core template_default files have been reviewed for HTML5 compliance, and a number of classes and IDs have been added to move older styling to CSS instead. Specific input-types like email/telephone for easier use on mobiles
• Admin: Admin menu improvements to help it fit tablet screens better
• Admin: Added customer-password reset via Admin
• Admin: Products Price Manager: Added display of taxes into prices
• Admin: Improvements to developers-toolkit and whos-online
• SEO: Numerous updates to canonical-url handling
• SEO: Added hreflang markup for better indexing of multilingual sites, and other HTML page-header metatag improvements
• Checkout: Order Details added to Checkout-Success page
• Payment: PayPal Express Checkout has numerous updated compatibilities added, including their latest InContext mobile support
• Payment: Added SagePay Form payment module (for hosted offsite PCI compliant credit card processing)
• Payment: Added First Data Hosted Checkout Payment Pages (Global Gateway e4) module (for hosted offsite PCI compliant credit card processing)
• Payment: Retired obsolete Linkpoint_API payment module (replaced by the new Payeezy JS module)
• Payment: Added Payeezy JS (First Data/Global Gateway e4) Payment module (for onsite PCI compliant credit card processing)
• Core: Added PHP 7.0 compatibility
• Core: Added MySQL 5.7 compatibility
• Core: Improved error-logging for troubleshooting (included @lat9's debug-backtrace mod)
• Core: Improved/simplified code for db query handling, allowing simple foreach() iterations instead of requiring while(!EOF) loops,
• Core: Added hooks to allow for 3rd-party-handling of taxes, for plugin support with orders, attributes, and much more
• Core: Fix some rounding errors
• Core: Added cron code for automated currency-updating, and currency sources can be selected from Admin->Config->My Store menu, and plugins can auto-show in this list
• Core: Fixed bug with a race condition causing database errors related to sessions
• Core: Simplified the configure.php file contents significantly by retaining only the most-often-customized components, and added an automatic-converter as part of zc_install's initial inspection
• Email: Integrated @lat9's "common CSS styling" for HTML emails
• Email: Added newer phpMailer integration (better compatibility with more email services), and email-failure errors are logged to /logs/ for easier debugging if problems occur
• Some language-file cleanups
• Improved compatibility for payment/shipping modules and SSL/TLS to work with the 2016 SHA-256 Secure Server initiatives being embraced by modern hosting companies and PCI Compliance
• Rewrote zc_install - fresh new look, will make future internal maintenance easier
• Replaced phpBB integration with generic hooks to allow for various external forums
• Security patches for alerts provided from various security watchdog sites
• ... and numerous other small improvements to make things work faster, sleeker, smarter and be easier to use

Help and Support

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