Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 27 ยท Shipping and maintenance

Packaging, Marketplace and Upgrades

Build an OpenCart .ocmod.zip, fill in install.json, plan upgrades with version numbers, keep one package working on 4.0.x and 4.1.x, and handle licensing and updates.

An extension is not finished when it works on your machine. It is finished when a merchant who has never met you can upload one file, click install, and end up with the same result you saw, and when version 1.3 can later replace version 1.2 without losing their settings. That is packaging and upgrading, and both are mostly about discipline: a predictable file layout, honest version numbers, and migrations that can be run in order.

This lesson covers the .ocmod.zip package, the metadata in install.json, what to check before you offer an extension on the OpenCart Marketplace or sell it yourself, and how to design upgrades. OpenCart cannot run on this site, so the real commands and files are read-only; the runnable examples are plain-PHP stand-ins (a version comparer, a compatibility checker and an upgrade planner) that work with the same ideas. For the folder layout itself, see Anatomy of an Extension.

What goes into the package

OpenCart 4's extension installer accepts a zip file whose name ends in .ocmod.zip. Inside, the folders are the ones you already know: admin/, catalog/, system/ (for example system/library or system/config), and an install.json file at the root. The installer unpacks it into extension/<vendor>/ and treats the files as an extension that can then be installed, configured and uninstalled from the admin.

TEXT
acme_badges.ocmod.zip
  install.json
  admin/
    controller/module/badge.php
    language/en-gb/module/badge.php
    view/template/module/badge.twig
  catalog/
    controller/event/badge.php
    model/badge.php
    view/template/module/badge.twig

Check the exact layout your target version expects against your development store, and keep the package layout matching what a working extension on that store has. Two mistakes cause most failed uploads: putting everything inside an extra top-level folder (the zip should start with install.json, not acme_badges/install.json), and including junk such as .git, .DS_Store, test folders or editor settings.

Building the zip

The command line builds the archive; run it from inside the extension folder so the paths start at the right place.

Terminal
# READ-ONLY: build the package from the extension's own folder
cd acme_badges
zip -r ../acme_badges-1.2.0.ocmod.zip . -x ".*" -x "tests/*" -x "*.md"

The -x patterns leave out hidden files, tests and documentation. If your file name includes the version, the upload still works as long as the name ends with .ocmod.zip; many developers keep a version in the file name so they can tell builds apart.

install.json: the metadata

install.json is a small JSON file that describes the package. The fields the installer shows in the admin are the extension name, its version, the author and a link to a support or product page. Treat these as required and keep them accurate, because they are what the merchant sees in the Installer list and what you will rely on when you ask "which version does this customer have?".

JSON
{
  "name": "Acme Product Badges",
  "version": "1.2.0",
  "author": "Acme Web Studio",
  "link": "https://acme.example.com/opencart/badges"
}

Your PHP code should read its own version from one place too. A common approach is a constant or a setting such as module_acme_badge_version written during install, so the code, install.json and your changelog cannot drift apart. Other optional fields may exist in newer OpenCart releases; read the changelog of the version you target rather than guessing.

PHP Validate an install.json before you zip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Version numbers you can trust

OpenCart itself uses four-part versions such as 4.0.2.3. For your own extension, use semantic versioning with three parts, MAJOR.MINOR.PATCH:

  • PATCH (1.2.0 to 1.2.1): bug fixes, no new features, no settings changes.
  • MINOR (1.2.0 to 1.3.0): new features that keep working with existing settings.
  • MAJOR (1.x to 2.0.0): changes that may break something, such as renamed settings or removed events.

Never compare versions as strings. The text "1.10.0" sorts before "1.9.0" alphabetically, but version 1.10.0 is newer. PHP's version_compare() compares each numeric part as a number, and it handles four-part OpenCart versions too.

PHP Compare versions and check compatibility

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Compatibility across 4.0.x and 4.1.x

Minor OpenCart releases are allowed to change internals, and in the 4.x series some changes affected extensions, for example how event actions name their methods and parts of the model and library APIs. Instead of memorising a list that goes stale, follow this process:

  1. Install each OpenCart version you claim to support in a separate test store, and run your extension through install, configure, use and uninstall on each.
  2. Read the upgrade notes and changelog between versions and search them for the classes and methods you call.
  3. Write your support range (4.0.2.0 up to, but not including, 4.2.0.0, for example) in your product description and in your own code.
  4. Isolate version-specific code in one small place. If the event separator or a method signature differs, one adapter class handles it and the rest of the extension stays the same.
PHP
<?php
// READ-ONLY: a guard in the install method of an admin controller
public function install(): void {
    if (version_compare(VERSION, '4.0.2.0', '<') || version_compare(VERSION, '4.2.0.0', '>=')) {
        $this->log->write('Acme Badges: unsupported OpenCart version ' . VERSION);
    }

    $this->load->model('extension/acme/module/badge');
    $this->model_extension_acme_module_badge->install();
}

VERSION is a constant OpenCart defines with its own version number. A guard like this is a warning, not a replacement for testing.

Upgrade scripts

When a merchant uploads version 1.3.0 over 1.1.0, the files are replaced, but the database is not. If 1.2.0 added a column and 1.3.0 added a table, your code must apply both, in order, exactly once. The reliable pattern:

  1. Store the installed schema version in a setting, for example module_acme_badge_schema.
  2. Keep a list of migrations, each with the version that introduced it.
  3. When the extension is installed or opened in the admin, compare the stored version with the code version and run every migration that is newer than the stored one and not newer than the code, in ascending order.
  4. After each successful migration, save its version, so a crash halfway can be resumed.
flowchart LR
    A["Stored schema<br/>1.1.0"] --> P["Planner"]
    B["Code version<br/>1.3.0"] --> P
    P --> M1["Run 1.2.0<br/>add column"]
    M1 --> M2["Run 1.3.0<br/>add table"]
    M2 --> S["Store schema<br/>1.3.0"]

The planner compares two versions and returns the migrations to run in order.

Make each migration safe to repeat where possible (CREATE TABLE IF NOT EXISTS, check for a column before adding it), because administrators click buttons twice and servers restart mid-request. Never edit a migration that has already shipped; add a new one.

PHP An upgrade-path planner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The planner uses version_compare() and a sorted list, which is the whole algorithm. In a real extension each entry would hold a function that runs SQL through $this->db->query(), and "store schema" would call the settings model after each step. Compare this with the install and uninstall methods in Install, Uninstall and Permissions.

Marketplace rules and quality

The OpenCart Marketplace is the official place to list extensions, and it has its own submission rules and review process that change over time, so read the current requirements on opencart.com before you submit. Whether you sell there, on your own site or to a single client, a good package shares the same traits:

  • Clean install and uninstall. Uninstalling removes your tables only if the merchant agrees, removes your events and permissions, and leaves no errors in the log.
  • No core edits. Use events and, as a last resort, OCMOD.
  • Security basics from Security for Extension Developers: escaped output, typed casts, permission checks.
  • Language files for every user-visible string, so translators do not need to edit code.
  • A changelog and a short manual with the supported OpenCart range, the PHP version you tested, and how to uninstall.
  • No phoning home without consent. If your extension contacts your server (for licence checks or update notices), document it and fail quietly when it cannot connect.

Licensing and updates

Decide how customers receive updates before you ship the first version. For a free extension, a new .ocmod.zip with a changelog is enough. For a paid one you need three things: a licence (terms about domains, number of stores and resale), a place customers can download new versions, and a way to tell them a new version exists. Keep the licence key check optional and non-blocking: a store that cannot reach your server must not lose its checkout.

Upgrades are normally done by uploading the new zip in the installer, which replaces the files. Tell customers to back up the database and files first, and to run the upgrade on a staging copy of busy stores. Each release note should list what changed, which migrations run, and whether any setting needs reviewing, using the patch, minor, major rules from earlier in this lesson.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which top-level layout should the .ocmod.zip have?

    The installer expects install.json and the extension folders at the root of the archive. An extra wrapper folder is a common reason an upload fails.
  2. 2. Why use version_compare() instead of comparing version strings with > ?

    version_compare() compares each numeric part as a number. Alphabetical comparison puts 1.10.0 before 1.9.0, which is wrong.
  3. 3. A merchant jumps from schema 1.1.0 to code 1.3.0. What should an upgrade routine do?

    Skipped versions still have migrations that were never applied. Running them in order and saving the version after each step makes the upgrade complete and resumable.
  4. 4. You add a new optional setting and fix two bugs, with no breaking changes. Which semantic-version bump fits?

    New features that keep existing settings working are a minor release. Patch releases are for fixes only, and major releases are for breaking changes.

Summary

  • Package as <name>.ocmod.zip with install.json and the extension folders at the root, and leave out hidden files, tests and documentation.
  • install.json carries the name, version, author and link; keep the version in one place in your code too.
  • Use semantic versions and compare them with version_compare(), never as strings.
  • Test every OpenCart version you claim to support, and keep version-specific code in one adapter.
  • Upgrades apply every missing migration in order, store progress, and never edit shipped migrations.
  • Offer a clean uninstall, a changelog, no core edits, and optional, non-blocking licence checks.

Next: Project: Weight and Zone Shipping Method