Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 27 ยท Getting started

Anatomy of an Extension

Learn how an OpenCart 4 extension is laid out: install.json, admin, catalog and system folders, vendor namespaces, type folders and the .ocmod.zip package.

An OpenCart extension is a folder of files that follows strict naming rules. The framework finds your code purely by those rules: there is no list of classes to register and no configuration file that says "my controller is over there". If a path, a namespace and a class name agree, it works. If one of the three is off by a letter, you get a blank page or a "class not found" error.

This lesson shows the layout you will use for every extension in the rest of the tutorial. You will see the files inside a small module, what install.json contains, how the vendor namespace works, and how the folders are zipped into an installable package. The runnable stand-ins check a package layout and verify that a class matches its path.

The vendor folder and the type folders

Everything an extension adds lives under extension/<vendor>/, where <vendor> is a short lowercase code for you or your company (we use acme). Inside it there are up to three sub-folders that mirror the application layout:

  • admin/ for back office code,
  • catalog/ for storefront code,
  • system/ for libraries and helpers shared by both (optional).

Inside admin/ and catalog/ you find the familiar controller, model, view and language folders. Below each of those goes a type folder named after what kind of extension this is: module, payment, shipping, total, theme and so on. Here is a complete, small module called hello_banner:

TEXT
extension/acme/
  install.json
  admin/
    controller/module/hello_banner.php
    language/en-gb/module/hello_banner.php
    view/template/module/hello_banner.twig
  catalog/
    controller/module/hello_banner.php
    language/en-gb/module/hello_banner.php
    view/template/module/hello_banner.twig

A module with an admin settings page and a storefront block. A model folder appears only when the extension needs one.

The admin side shows the settings form; the catalog side renders the banner for shoppers. Notice the same name, hello_banner, repeated in the file names of every part. That name plus the vendor and type forms the route to the code: extension/acme/module/hello_banner.

Language files sit in a folder named after the language code, for example en-gb. Add another folder (de-de, fr-fr) per translation. OpenCart falls back to the default language for missing strings, so you can ship English first and translate later.

install.json

At the root of the extension is install.json, a small file of metadata that the installer and the admin screens read:

JSON
{
  "name": "Hello Banner",
  "description": "Shows a configurable greeting banner on the storefront.",
  "version": "1.0.0",
  "author": "Acme Web Studio",
  "link": "https://acme.example/hello-banner"
}

The installer uses these fields to list the extension in the installer screen, so keep the version a proper semantic version like 1.0.0; Packaging, Marketplace and Upgrades uses it for upgrade checks. Requirements of the field list differ slightly between 4.x releases, so compare against an extension that installs cleanly on your target version.

Namespaces and class names

Each file declares a namespace that repeats its location. Take the storefront controller from the tree above:

PHP
<?php
namespace Opencart\Catalog\Controller\Extension\Acme\Module;

class HelloBanner extends \Opencart\System\Engine\Controller {
    public function index(): string {
        return '<div class="hello">Hello from Acme!</div>';
    }
}

The rules behind it are mechanical:

  1. The namespace starts with Opencart\, then the application (Catalog or Admin), then the kind of class (Controller, Model).
  2. After that comes Extension\, your vendor (Acme), the type folder (Module), each in StudlyCase.
  3. The class name is the file name in StudlyCase: hello_banner.php becomes HelloBanner.
  4. The parent class comes from the System\Engine namespace (Controller or Model).

If you mistype one segment, PHP will not find the class, and the error message talks about the class name rather than the real cause. When you see "class not found", compare the file path with the namespace character by character.

The vendor segment also protects you from collisions. Two developers can both write a module called hello_banner, because one lives in extension/acme/ and the other in extension/zenith/. Pick your vendor code once and keep it for all your products.

Extension types

The type folder is not just decoration. The admin lists extensions by type (Extensions > Extensions, choose a type from the drop-down), and each type has its own contract:

Type folder Contract in one line
module An index() method that returns HTML for a layout position
payment A way to offer and complete payment at checkout
shipping A getQuote() method that returns shipping options
total A getTotal() method that adds a line to the order totals
theme Controls template and style resolution for the storefront

Later chapters give every type a dedicated lesson. For now it is enough to know that the folder name must match one of the types the admin knows about, or your extension will never appear in the list.

Building the package

You distribute an extension as a zip file with the double extension .ocmod.zip, for example acme_hello_banner.ocmod.zip. The admin Extensions > Installer screen uploads it and the installer unpacks the files into place. In the commonly used 4.0.2 layout the archive has install.json at its root with the admin, catalog and system folders beside it, and the installer copies them under extension/<vendor>/:

Terminal
cd extension/acme
zip -r ../../acme_hello_banner.ocmod.zip install.json admin catalog

Keep the archive free of stray files such as .git, editor backups or .DS_Store. Details of the package layout have shifted slightly between 4.x releases, so the surest method is to unzip an extension that installs on your target version and copy its shape. After uploading, the extension appears under Extensions > Extensions in its type list, where you click the green Install button, grant permissions and open its settings. That sequence is covered in Install, Uninstall and Permissions.

flowchart TD
    A["acme_hello_banner.ocmod.zip"] --> B["Extensions > Installer<br/>(upload)"]
    B --> C["Files copied to<br/>extension/acme/"]
    C --> D["Extensions list<br/>(choose type, click Install)"]
    D --> E["Settings page and<br/>storefront layout"]

From zip file to working extension: upload, copy, install, configure.

Checking a layout automatically

Typos in file names are the most common beginner mistake, and they are cheap to detect with a script. The stand-in below receives a list of paths (as if listed from a zip) and reports problems: a missing install.json, files outside the three allowed folders, unknown types, invalid names, and an admin part without its matching language file.

PHP A package layout validator

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.

A validator like this belongs in your build script. It costs nothing, and it catches the mistake before a customer does.

Checking a class against its path

The second common mistake is a namespace that does not match the path. The next stand-in takes a file path and the source of the class inside it, derives the expected namespace and class name, and compares them.

PHP Does the namespace match the path?

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 stand-in does not execute the class; it only compares names. That is enough to find the problem that usually costs an hour.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file name gives the class HelloBanner in OpenCart 4?

    File names are lowercase snake_case, and underscores become StudlyCase in the class name.
  2. 2. What is the purpose of the vendor folder under extension/?

    The vendor segment is part of the namespace and the route, so two developers can use the same extension name without clashing.
  3. 3. Which file holds the extension's name, version and author for the installer?

    install.json is the metadata file at the root of the package.
  4. 4. A shipping extension would normally put its controller under which folder?

    The type folder shipping is inside the controller folder, with the same layout under admin/ for settings.

Summary

  • An extension lives under extension/<vendor>/ with admin, catalog and optional system folders.
  • Inside them, controller, model, view and language folders hold a type folder such as module or payment.
  • Path, namespace and class name must agree: hello_banner.php is ...\Extension\Acme\Module\HelloBanner.
  • install.json carries metadata; the package is a .ocmod.zip.
  • Layout details vary slightly between 4.x releases, so copy the shape of a package that installs on your target version, and automate layout checks.

Next: Routing and Controllers