A Comprehensive Guide to Developing Extensions for OpenCart 4

• OpenCart 4 extensions follow a self‑contained directory structure under /extension/{vendor}/, replacing the scattered file placement used in previous versions.
• OpenCart 4.1.0.0 restored the OCMOD modification system after it was removed in early 4.0.x releases, giving developers a familiar way to modify core behaviour alongside the event system.
• OpenCart 4.2 introduced Tasks – background processes for operations that do not require immediate feedback, similar to scheduled jobs or cron tasks.
• The event system remains the primary extension mechanism for hooking into core functionality without modifying core files, with events triggered at key points in controllers, models, and views.
• OpenCart 4 requires PHP 8.0+ and uses namespaced classes following an MVC‑A (Model‑View‑Controller‑Action) pattern.

1. Download OpenCart 4: Obtain the latest stable version from the official OpenCart website. For 2026, this means version 4.1.x or newer.
2. Extract files: Unzip the downloaded archive and place the contents in your web server’s document root or a local development directory.
3. Create a database: Set up a new MySQL or MariaDB database for your OpenCart installation.
4. Run the installer: Access the installation script via your browser and follow the on‑screen instructions. The installer checks for PHP version and extension requirements.

• PHP 8.0 or higher (PHP 8.1+ recommended)
• MySQL 5.6+ or MariaDB 10.1+
• Web server: Apache with mod_rewrite or Nginx
• Extensions: PDO, OpenSSL, cURL, JSON, XML, and GD

• IDE: Visual Studio Code, PhpStorm, or Sublime Text with PHP and Twig support
• Version control: Git for tracking changes
• Local server: XAMPP, MAMP, Laravel Valet, or Docker (the official OpenCart Docker image is available)
• Composer: Dependency manager used by OpenCart 4 core

extension/
└── {vendor}/
 └── {extension_name}/
 ├── admin/
 │ ├── controller/
 │ ├── model/
 │ ├── view/
 │ │ └── template/
 │ └── language/
 ├── catalog/
 │ ├── controller/
 │ ├── model/
 │ ├── view/
 │ │ └── template/
 │ └── language/
 ├── system/
 │ └── library/ # For custom classes
 ├── install.sql # Database installation script
 ├── install.php # Installation logic
 └── uninstall.sql # Database uninstallation script

// In your extension's install() method
$this->load->model('setting/event');
$this->model_setting_event->addEvent(
 'your_extension_code',
 'catalog/controller/common/header/before',
 'extension/your_vendor/your_extension/event/header'
);

• If you are targeting OpenCart 4.1.x or newer, you have both options available
• For new extensions, prefer the event system over OCMOD where possible-it is more maintainable and less likely to cause conflicts
• Use OCMOD only when you need to modify core behaviour that events cannot cover

• Sending bulk emails
• Generating reports
• Synchronising data with external systems
• Processing queued jobs

• Purpose: What problem does your extension solve?
• Features: What functionality will it provide?
• User interface: Will it have admin settings? Does it modify the storefront?
• Extension type: Module, payment gateway, shipping method, theme, or other.

extension/
└── yourvendor/
 └── examplemodule/
 ├── admin/
 │ ├── controller/
 │ │ └── module.php
 │ ├── model/
 │ │ └── module.php
 │ ├── view/
 │ │ └── template/
 │ │ └── module.twig
 │ └── language/
 │ └── en-gb/
 │ └── module.php
 ├── catalog/
 │ ├── controller/
 │ │ └── module.php
 │ ├── model/
 │ │ └── module.php
 │ ├── view/
 │ │ └── template/
 │ │ └── module.twig
 │ └── language/
 │ └── en-gb/
 │ └── module.php
 ├── install.sql
 └── install.php

<?php
namespace Opencart\Admin\Controller\Extension\YourVendor\ExampleModule;
class Module extends \Opencart\System\Engine\Controller
{
 public function index(): void
 {
 $this->load->language('extension/yourvendor/examplemodule/module');
 $this->document->setTitle($this->language->get('heading_title'));
 $data['breadcrumbs'] = $this->getBreadcrumbs();
 // Load your settings from the database
 $data['module_status'] = $this->config->get('module_example_status');
 $data['header'] = $this->load->controller('common/header');
 $data['column_left'] = $this->load->controller('common/column_left');
 $data['footer'] = $this->load->controller('common/footer');
 $this->response->setOutput($this->load->view('extension/yourvendor/examplemodule/module', $data));
 }
 protected function getBreadcrumbs(): array
 {
 $breadcrumbs = [];
 $breadcrumbs[] = [
 'text' => $this->language->get('text_home'),
 'href' => $this->url->link('common/dashboard', 'user_token=' . $this->session->data['user_token'])
 ];
 $breadcrumbs[] = [
 'text' => $this->language->get('text_extension'),
 'href' => $this->url->link('marketplace/extension', 'user_token=' . $this->session->data['user_token'] . '&type=module')
 ];
 $breadcrumbs[] = [
 'text' => $this->language->get('heading_title'),
 'href' => $this->url->link('extension/yourvendor/examplemodule/module', 'user_token=' . $this->session->data['user_token'])
 ];
 return $breadcrumbs;
 }
}

<?php
namespace Opencart\Admin\Model\Extension\YourVendor\ExampleModule;
class Module extends \Opencart\System\Engine\Model
{
 public function install(): void
 {
 // Create database tables
 $this->db->query("
 CREATE TABLE IF NOT EXISTS `" . DB_PREFIX . "example_module` (
 `example_module_id` INT(11) NOT NULL AUTO_INCREMENT,
 `name` VARCHAR(255) NOT NULL,
 `status` TINYINT(1) NOT NULL DEFAULT 0,
 PRIMARY KEY (`example_module_id`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
 ");
 }
 public function uninstall(): void
 {
 $this->db->query("DROP TABLE IF EXISTS `" . DB_PREFIX . "example_module`;");
 }
 public function getSettings(): array
 {
 $query = $this->db->query("SELECT * FROM `" . DB_PREFIX . "example_module`");
 return $query->rows;
 }
}

{{ header }}{{ column_left }}
<div id="content">
 <div class="page-header">
 <div class="container-fluid">
 <div class="float-end">
 <button type="submit" form="form-module" data-toggle="tooltip" title="{{ button_save }}" class="btn btn-primary">
 <i class="fa-solid fa-save"></i>
 </button>
 <a href="{{ back }}" data-toggle="tooltip" title="{{ button_back }}" class="btn btn-light">
 <i class="fa-solid fa-reply"></i>
 </a>
 </div>
 <h1>{{ heading_title }}</h1>
 <ol class="breadcrumb">
 {% for breadcrumb in breadcrumbs %}
 <li class="breadcrumb-item">
 <a href="{{ breadcrumb.href }}">{{ breadcrumb.text }}</a>
 </li>
 {% endfor %}
 </ol>
 </div>
 </div>
 <div class="container-fluid">
 <div class="card">
 <div class="card-header"><i class="fa-solid fa-pencil"></i> {{ text_edit }}</div>
 <div class="card-body">
 <form id="form-module" method="post" action="{{ save }}" data-oc-toggle="ajax">
 <div class="row mb-3">
 <label class="col-sm-2 col-form-label" for="input-status">{{ entry_status }}</label>
 <div class="col-sm-10">
 <div class="form-check form-switch form-switch-lg">
 <input type="hidden" name="module_example_status" value="0"/>
 <input type="checkbox" name="module_example_status" value="1" id="input-status" class="form-check-input"{% if module_example_status %} checked{% endif %}/>
 </div>
 </div>
 </div>
 </form>
 </div>
 </div>
 </div>
</div>
{{ footer }}

<?php
// Heading
$_['heading_title'] = 'Example Module';
// Text
$_['text_extension'] = 'Extensions';
$_['text_success'] = 'Success: You have modified Example Module!';
$_['text_edit'] = 'Edit Example Module';
$_['text_footer_message'] = 'This is an example module for OpenCart 4.';
// Entry
$_['entry_status'] = 'Status';
// Error
$_['error_permission'] = 'Warning: You do not have permission to modify Example Module!';

<?php
// Install script for Example Module
$installer = $this;
$installer->load->model('setting/event');
// Register an event listener
$installer->model_setting_event->addEvent(
 'example_module',
 'catalog/controller/common/header/before',
 'extension/yourvendor/examplemodule/event/header'
);

1. Ensure your extension files are in the correct directory structure under extension/{vendor}/{extension_name}/
2. Zip the contents of the extension folder-not the folder itself
3. The resulting ZIP file should have extension/ as the top‑level directory
4. Upload via Extensions > Installer in the admin panel

Important: Although OCMOD extensions still require the .ocmod.zip extension in some contexts, this naming convention is a remnant of OpenCart 3 and does not indicate active OCMOD functionality in all versions. For 4.1.x and newer, the installer handles both .zip and .ocmod.zip files.

• Installation and uninstallation work correctly
• Events fire as expected
• No conflicts with other extensions

• Page load times with the extension enabled and disabled
• Database query counts
• Memory usage

• All PHP, Twig, and language files
• Installation scripts
• Documentation (README, installation guide)

• Installation instructions
• Configuration steps
• Troubleshooting tips
• Changelog

1. OpenCart 4 uses a self‑contained extension directory under /extension/{vendor}/, replacing the scattered file placement of OpenCart 3.
2. OCMOD was restored in OpenCart 4.1.0.0 after being removed in early 4.0.x releases. For OpenCart 4.1.x and newer, both the event system and OCMOD are available.
3. The event system remains the primary extension mechanism for hooking into core functionality without modifying core files.
4. OpenCart 4.2 introduced Tasks-background processes for operations that do not require immediate feedback.
5. OpenCart 4 requires PHP 8.0+ and uses namespaced classes with an MVC‑A pattern.
6. Extensions are packaged as ZIP archives and installed via the admin panel’s Extensions > Installer.
7. Regular maintenance-bug fixes, compatibility updates, and user support-is essential for a successful extension.

• OpenCart Official Website
• OpenCart Documentation
• OpenCart GitHub Repository
• OpenCart Marketplace
• Stack Overflow – OpenCart Questions