Creating an extension

An extension is a folder with your code that the shop installs and removes as one piece. Until now the files were put next to the core; from this lesson on everything lives in extension/acme_hello/. Core files stay unchanged, so the shop can be updated.

Structure

Inside, an extension repeats the structure of the core: an admin part and a catalog part, each with controllers, models, templates and language files.

acme_hello/
├── install.json
├── admin/
│   ├── controller/module/acme_hello.php
│   └── language/en-gb/module/acme_hello.php
└── catalog/

The folder module is the type of the extension. Other types: payment, shipping, total, theme, report. Create this folder anywhere on your computer — it gets into the shop through the installer.

install.json

The file in the root of the extension describes it:

{
    "name": "Acme Hello",
    "version": "1.0.0",
    "author": "Acme",
    "link": "https://example.com"
}

These values are shown in the list of installed packages.

The smallest admin part

For the extension to appear in the list of modules it needs an admin controller and a language file with its name:

// admin/language/en-gb/module/acme_hello.php
$_['heading_title'] = 'Acme Hello';

// admin/controller/module/acme_hello.php
namespace Opencart\Admin\Controller\Extension\AcmeHello\Module;
 
class AcmeHello extends \Opencart\System\Engine\Controller
{
    public function index(): void
    {
        $this->response->setOutput('Acme Hello settings');
    }
}

The controller only prints a line; the next lesson turns it into a settings page.

Names

What	Rule	Value
Folder and archive	Lowercase letters, digits, underscore	`acme_hello`
Namespace	`Extension`, the folder name in CamelCase, the type	`Opencart\Admin\Controller\Extension\AcmeHello\Module`
Route	`extension/`, the folder, the type, the file	`extension/acme_hello/module/acme_hello`

Packaging

The contents of the folder — not the folder itself — are packed into a zip archive whose name ends with .ocmod.zip:

cd acme_hello
zip -r ../acme_hello.ocmod.zip .

The name of the archive before .ocmod.zip becomes the name of the folder in extension/.

Installing

In the admin panel open Extensions → Installer, upload acme_hello.ocmod.zip and press the install button in its row. The files are unpacked into extension/acme_hello/.
Open Extensions → Extensions, choose the type Modules, find «Acme Hello» and press the install button.
Press the edit button in the same row.

The page admin/index.php?route=extension/acme_hello/module/acme_hello&user_token=... opens and shows «Acme Hello settings».

After installation the files can be edited right in extension/acme_hello/ — there is no need to repack the archive after every change. A new archive is built when the extension is handed over to another shop.

Common mistake

The archive is made from the folder itself, so inside it there is acme_hello/install.json instead of install.json. The installer does not find the description and refuses the package. Open the archive: install.json, admin and catalog must be at its top level.

Thanks for reading!