Zencart

Zen Cart Plugin Development

Overview

Zen Cart is an open-source PHP e-commerce platform forked from osCommerce in 2003, maintained by a community of developers. It emphasizes ease of use for non-technical store owners while preserving deep customizability for developers. Zen Cart is built on procedural and class-based PHP without a modern framework dependency -- there is no Symfony, Laravel, or Composer requirement in core. The platform uses a MySQL database, a custom template system, and a distinctive observer/notifier event-driven architecture for extensibility.

Zen Cart's codebase separates into three top-level directories: includes/ (storefront), admin/ (back office), and zc_plugins/ (encapsulated plugins, introduced in 1.5.7). The storefront follows an auto-loading initialization sequence where configuration files, class files, language files, and module files load in a deterministic order controlled by numbered auto-loader entries. Understanding this auto-loading sequence is essential for plugin development because it determines when custom code initializes relative to core subsystems.

Extension Model

Zen Cart provides three primary extension mechanisms:

• Observer/Notifier system -- The core extension pattern. Core code fires notifications at key lifecycle points (order processing, checkout, admin operations). Plugins attach observer classes that react to these notifications. This decouples custom logic from core files entirely.
• Auto-loading -- A numbered initialization system that controls load order for classes, configuration, and initialization scripts. Plugins register auto-loader entries to ensure their classes load at the correct point in the startup sequence.
• Template overrides -- A cascading file resolution system where storefront template files, language files, and certain class files can be overridden per-template without modifying core files. The system checks the active template directory first, then falls back to the default.

For encapsulated plugin architecture (1.5.7+), manifest files, installer classes, and file mapping conventions, see references/plugin-architecture.md.

Module Types

Zen Cart organizes functional extensions into module categories, each following specific interfaces:

• Payment modules -- Integrate payment gateways into checkout. Each payment module is a PHP class in includes/modules/payment/ implementing standard methods: __construct(), selection(), pre_confirmation_check(), confirmation(), process_button(), before_process(), after_process(), and after_order_create(). Payment modules define configuration keys installed via the admin.
• Shipping modules -- Calculate shipping rates. Classes reside in includes/modules/shipping/ and implement quote() to return rate arrays. Shipping modules receive destination zone, weight, and cart contents as inputs.
• Order Total modules -- Add line items to the order total calculation (subtotal, tax, shipping, discounts, coupons, gift certificates). Classes in includes/modules/order_total/ implement process() and output() methods, executing in a configurable sort order.
• Encapsulated plugins (1.5.7+) -- Self-contained plugin packages in the zc_plugins/ directory with a manifest file, versioned directory structure, and automatic file mapping. Encapsulated plugins can include admin pages, storefront code, observer classes, and SQL installers without touching core directories. This is the recommended approach for new development.

Observer/Notifier System

The observer/notifier pattern is the primary mechanism for extending Zen Cart without modifying core files. Core classes extend base (the notifier base class) and call $this->notify('NOTIFY_EVENT_NAME') at strategic points. Observer classes register interest in specific notifications and execute custom logic when those notifications fire.

Core Concepts

• Notifiers -- Core code calls $this->notify('EVENT_NAME', $param1, &$param2). Parameters after the event name pass contextual data. Parameters passed by reference allow observers to modify core behavior.
• Observers -- Classes that extend base and call $this->attach($this, array('NOTIFY_EVENT_NAME')) in their constructor. When the notification fires, Zen Cart calls the observer's update() method (or a specifically named method like updateNotifyEventName()).
• Auto-loader registration -- Observer classes must be registered in the auto-loader system to instantiate at startup. Create an auto-loader entry file that loads the observer class at an appropriate point in the initialization sequence.

Key Notification Events

Zen Cart fires hundreds of notifications across the order lifecycle, checkout flow, and admin operations. Critical events include notifications for order creation, payment processing, email dispatch, cart modifications, customer registration, and admin product updates.

For the complete observer/notifier pattern documentation, event catalog, and implementation examples, see references/observer-notifier.md.

Template Override System

Zen Cart's template system allows overriding storefront display files without editing core templates. When rendering a page, the system checks multiple directories in priority order:

1. includes/templates/ACTIVE_TEMPLATE/ -- Active template directory (highest priority).
2. includes/templates/template_default/ -- Default template fallback.
3. Core directories -- Base files if no override exists.

This cascading resolution applies to template files (.php), CSS, JavaScript, language files, and certain module files. Override any storefront page by placing a file with the same relative path inside the active template directory.

Template overrides extend to language files (includes/languages/LANGUAGE/TEMPLATE/) and extra definitions, allowing per-template string customization without modifying shared language files.

Development Setup

Local Installation

1. Install PHP 7.4+ (PHP 8.0-8.2 supported in Zen Cart 1.5.8+) with extensions: mysqli, curl, gd, zlib, openssl.
2. Install MySQL 5.7+ or MariaDB 10.2+.
3. Install Apache with mod_rewrite enabled (Nginx also works with rewrite rules).
4. Download Zen Cart from the official site or GitHub repository.
5. Run the web-based installer at /zc_install/.
6. Rename or delete /zc_install/ and rename the admin directory to a random name for security.

Development Workflow

• No Composer or build tooling required -- Zen Cart is plain PHP.
• Enable debug logging by setting DEBUG_AUTOLOAD and reviewing logs/ directory output.
• Use the admin > Modules interface to install/remove payment, shipping, and order total modules.
• For encapsulated plugins, place the plugin directory in zc_plugins/ and use the admin Plugin Manager to install.
• Clear cached language files and template caches when modifying language or template override files.

Anti-Patterns

• Editing core files directly. Use observer/notifier hooks, template overrides, or encapsulated plugins. Core edits are overwritten on upgrades.
• Ignoring auto-loader load order. Observer classes that load before their dependencies cause fatal errors. Match auto-loader point numbers to the correct initialization phase.
• Hardcoding database table prefixes. Always use TABLE_ constants (e.g., TABLE_ORDERS, TABLE_PRODUCTS). Zen Cart installations may use custom prefixes.
• Skipping zen_db_input() / zen_db_prepare_input(). All user input in database queries must be sanitized. Zen Cart does not use parameterized queries by default.
• Modifying configure.php for plugin settings. Use the configuration table via admin-managed configuration keys. Store module settings using the standard MODULE_PAYMENT_* / MODULE_SHIPPING_* constant pattern.

Reference Files

• Plugin Architecture -- Encapsulated plugins (1.5.7+), directory structure, manifest.php, installer classes, version management, legacy plugin conventions, file mapping
• Observer/Notifier System -- Observer/notifier pattern, base class, NOTIFY_ constants, observer registration, event catalog, creating custom notifications