Build Your First OpenCart 4 Module: A Step-by-Step Guide

Build Your First OpenCart 4 Module: A Step-by-Step Guide

OpenCart 4 is an open-source PHP/MySQL platform that uses an MVC-L architecture: Model, View, Controller, and Language. In this guide we will build a simple extension that has a settings form on the admin side and displays a greeting message on the storefront. The goal is to understand the file structure, not to write complex code.

The MVC-L structure

OpenCart clearly separates the admin and catalog (storefront) sides with separate controllers. Each module usually has four types of file.

Step 1. Admin controller and language file

Create a controller in admin/controller/extension/hello/module/hello.php. The controller loads the language file, reads settings from the settings model, and passes them to the template. The language file admin/language/en-gb/extension/hello/module/hello.php holds all interface texts without hard-coding them in the controller.

Step 2. Admin template (Twig)

The settings form is written in a Twig template at admin/view/template/extension/hello/module/hello.twig. Here you build an HTML form with fields (for example, a greeting text and an enabled status) that are saved in the setting table through OpenCart's standard settings system.

Step 3. Saving settings

In OpenCart 4, module settings are usually stored as setting keys (for example, module_hello_status and module_hello_text). The admin controller handles the save action, validates input, and stores the values. It is important to check the user's permission before saving.

Step 4. The catalog (storefront) side

On the storefront, create a separate controller at catalog/controller/extension/hello/module/hello.php that reads the saved setting and renders the Twig template catalog/view/template/extension/hello/module/hello.twig. This way the same module has separate logic for the admin and public sides.

Step 5. Packaging as OCMOD

In OpenCart 4, extensions are distributed as an OCMOD package - a ZIP archive with an install.json file at its root. The install.json describes the name, version, author, and compatible OpenCart version. The files are placed in their matching folders inside the archive.

Step 6. Installing from the Extensions menu

Log in to the admin panel, go to the Extensions section, upload the ZIP via the Extension Installer, then activate the module in the Modules list. After that you can open the settings form, fill in the greeting text, and check the result on the store page.

Conclusion: Building your first module is mostly a matter of understanding the MVC-L structure and packaging correctly with OCMOD. Once you master this pattern, you can create more complex extensions on the same foundation.