`).
* Incorrect CSS classes.
* JavaScript conflicts.
* Override code that removes essential markup.
**Solution:**
1. **Compare with Original**: Open the original `.twig` file and compare it with your override.
2. **Browser Inspector**: Use the browser’s developer tools to identify missing or broken elements.
3. **Revert Gradually**: Remove sections of your custom code until the layout stabilizes, then isolate the problematic code.
Multi‑Store Override Issues
**Problem: Override works on one store but not another**
**Diagnostic Steps:**
1. **Store Selection**: Confirm the override is assigned to the correct store.
2. **Fallback Check**: If a store‑specific override is missing, OpenCart falls back to the default store’s template.
3. **Template Paths**: Verify that the template path exists for that store (some extensions may not be installed on all stores).
**Quick Solutions:**
* Create a separate override for each store that needs customization.
* Use the default store override as a fallback for all stores.
{% hint style="info" %}
**Advanced Theme Development** 🛠️ For complex theme modifications beyond simple template overrides:
* Create a full custom theme in `catalog/view/theme/yourtheme/`
* Use template inheritance and overrides at the file level
* Develop custom extensions with their own templates
{% endhint %}
# Language Editor
Editing language translations and text strings in OpenCart 4
## Video Tutorial
{% embed url="
" %}
*Video: Using the Language Editor in OpenCart 4*
## Introduction
The Language Editor in OpenCart 4 is a powerful tool that allows you to override any text string in your store without modifying the physical language files. This ensures your customizations are "update-safe," meaning they won't be lost when you upgrade OpenCart or your extensions. It's the ideal way to customize branding, improve messaging, or fix translation errors.
## Language Editor List
The Language Editor list shows all the active translation overrides in your store. From this interface, you can:
* **Add New**: Create a new translation override.
* **Edit**: Modify an existing override.
* **Delete**: Remove an override and revert to the default text.
* **Filter**: Search for specific overrides by store, language, or route.
{% hint style="info" %}
**Pro Tip**: Overrides are stored in the database. If you want to revert to the original text provided by OpenCart or an extension, simply delete the entry in the Language Editor.
{% endhint %}
## Creating a Translation Override
To change a specific piece of text on your storefront or admin panel, follow these steps:
{% stepper %}
{% step %}
#### Access the Editor
1. Log in to your OpenCart admin panel.
2. Navigate to **Design → Language Editor**.
3. Click the **Add New** (+) button.
{% endstep %}
{% step %}
#### Select Route and Key
1. **Store**: Choose the store where the change should apply.
2. **Language**: Select the target language.
3. **Route**: Select the page or module where the text is located (e.g., `common/header` for the header).
4. **Key**: Select the specific text variable from the dropdown. OpenCart 4 automatically populates this list based on the Route you selected.
{% endstep %}
{% step %}
#### Set New Value
1. **Default**: This field shows the current text for reference.
2. **Value**: Enter your new custom text.
3. Click **Save**.
{% endstep %}
{% endstepper %}
## Language Editor Form
### Configuration Fields
* **Store**: Allows you to have different text for the same item on different sub-stores.
* **Language**: Essential for multi-language stores to ensure the right translation is updated.
* **Route**: The internal path to the language file. For example, `checkout/checkout` contains strings for the checkout page.
* **Key**: The specific identifier for the text string. In OpenCart 4, this is a searchable dropdown, making it easy to find the exact string you need.
* **Default**: Displays the original text from the language file so you know what you are changing.
* **Value**: Your custom text. This is what will be displayed on the storefront.
{% hint style="success" %}
**Finding the Route**: If you're unsure which route contains the text you want to change, look at the URL of the page. For a product page, the route is usually `product/product`. For the contact page, it's `information/contact`.
{% endhint %}
## Best Practices
Customization Strategy
**Branding & Consistency**
**Consistent Tone:**
* **Brand Voice**: Use the Language Editor to ensure all buttons and messages match your brand's personality (e.g., changing "Add to Cart" to "Add to Bag").
* **Terminology**: Use consistent terms throughout the store to avoid confusing customers.
* **Clarity**: Rewrite technical or vague error messages into helpful, user-friendly instructions.
**Maintenance:**
* **Keep it Minimal**: Only override strings you actually need to change to keep the list manageable.
* **Document Changes**: Keep a note of why certain strings were changed, especially for legal or compliance reasons.
{% hint style="success" %}
**UX Tip**: Small changes like changing "Register Account" to "Join the Club" can significantly impact user engagement and conversion rates.
{% endhint %}
Multi-Language & Multi-Store
**Global Management**
**Localization:**
* **Regional Idioms**: Use the editor to adapt a general language pack to a specific region (e.g., UK English vs. US English).
* **Store Variation**: If you run multiple stores (e.g., B2B and B2C), you can use different labels for the same keys to suit the different audiences.
**Accuracy:**
* **Check Length**: Ensure your translated text isn't significantly longer than the original, as it might break your theme's layout.
* **Variable Preservation**: Be careful not to delete placeholders like `%s` in strings (e.g., `Showing %s to %s of %s`), as these are replaced by numbers dynamically.
{% hint style="info" %}
**Hreflang & SEO**: Changing text via the Language Editor is SEO-friendly as it changes the actual HTML output that search engines crawl.
{% endhint %}
## Common Tasks
{% stepper %}
{% step %}
#### Changing "Add to Cart" to "Buy Now"
1. Navigate to **Design → Language Editor** and click **Add New**.
2. Select your **Store** and **Language**.
3. Set **Route** to `common/language` or the specific product route `product/product`.
4. Find the **Key** `button_cart`.
5. Enter "Buy Now" in the **Value** field and **Save**.
{% endstep %}
{% step %}
#### Customizing the Welcome Message
1. In the Language Editor, add a new entry.
2. Select **Route** `common/header`.
3. Find a key like `text_welcome` (if applicable to your theme) or similar.
4. Enter your custom greeting and **Save**.
{% endstep %}
{% endstepper %}
## Warnings and Limitations
{% hint style="danger" %}
**Critical Warnings**
* **Placeholders**: Never remove or change the order of placeholders like `%s`, `%d`, or `{variable}`. These are required for the system to insert dynamic data.
* **HTML Tags**: Some strings allow HTML, others don't. Adding HTML to a string that doesn't expect it can break the page layout or cause security issues.
* **Cache**: After saving a translation, you may need to clear your theme and SASS cache in the admin dashboard (Developer Settings) to see the changes.
* **Update Persistence**: While Language Editor changes are update-safe, if an extension changes its internal "Key" names in a new version, your old override may stop working.
{% endhint %}
## Troubleshooting
Changes Not Appearing
**Problem: You saved a translation but the old text still shows.**
**Diagnostic Steps:**
1. **Cache Check**: Click the blue gear icon on the main Dashboard and clear both Theme and SASS cache.
2. **Route Check**: Ensure you selected the correct Route. Some text appears in multiple places (e.g., "Add to Cart" appears in `product/product`, `product/category`, and modules).
3. **Store Check**: Verify you are viewing the same store that you applied the override to.
**Quick Solutions:**
* Clear your browser cache.
* If using a 3rd-party theme, check if they have their own translation system or cache.
Finding the Correct Key
**Problem: There are too many keys in the dropdown and you can't find the right one.**
**Diagnostic Steps:**
1. **Search**: Use the browser's search function (Ctrl+F) within the Key dropdown to find the default text.
2. **File Inspection**: If you still can't find it, you may need to check the actual language file via FTP (e.g., `catalog/language/en-gb/checkout/checkout.php`) to see the key name.
**Quick Solutions:**
* Look for common prefixes: `text_` for labels, `button_` for buttons, `error_` for errors.
> "The Language Editor is the bridge between a generic store and a personalized brand experience. It gives you total control over your store's voice without touching a single line of code."
# Coding Standard
### File types & encoding
All PHP files with the exception of view/template files have the extension .php
All view/template files have the extension .twig
Line feeds are handled automatically by Git, the repo is managed using LF. When cloning all line feeds will be converted automatically to your native environment (CRLF for Windows, LF for Mac/Linux).
### PHP Tags
Short PHP opening tags and ASP tags are not supported. The characters should be lowercase.
`
```
### Indentation
PHP files must be indented using the TAB character. 4 space tabs are not supported.
HTML in template files (.twig) must be indented using 2 spaces, not 4 spaces or TABS. JavaScript must be indented using the TAB character.
### Spacing
IF, WHILE, FOR etc should have a space before and after the brackets.
**Correct**
```
if () {
```
**Incorrect**
```
if(){
```
ELSE etc should have a space after and before the curly braces
**Correct**
```
} else {
```
**Incorrect**
```
}else{
```
Type casting does NOT have a space before the variable
**Correct**
```
(int)$var
```
**Incorrect**
```
(int) $var
```
Setting a variable should always have a space before and after the equals sign
**Correct**
```
$var = 1;
```
**Incorrect**
```
$var=1;
```
### Whitespace
After any code, but before a new line - there should be no white space. The same is true for an empty line.
After the closing PHP tag it is extremely important to remove any white space.
### New Lines
Opening curly braces do not go onto a new line, they will always have a space before and be on the same line.
1 True Brace Style (1TBS) ([WIKI](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS))
**Correct**
```
if ($my_example == 1) {
class ModelExampleExample extends Model {
public function addExample() {
} else {
```
**Incorrect**
```
if ($my_example == 1)
{
class ModelExampleExample extends Model
{
public function addExample()
{
}
else
{
```
### File naming
All files should be in lower case and words separated by an underscore.
### Class & method naming
Class names and method names should be camel case.
**Correct**
```
class ModelExampleExample extends Model
public function addExample()
```
**Incorrect**
```
class model_exampleexample extends Model
public function add_example()
```
A method scope should always be cast.
**Correct**
```
public function addExample()
```
**Incorrect**
```
function addExample()
```
### PHP Function (helpers) naming
Helper function names should be lower case and an underscore used to separate words.
### PHP variable naming
PHP variables should be lower case and an underscore used to separate words.
**Correct**
```
$var = 123;
$new_var = 12345;
```
**Incorrect**
```
$Var = 123;
$newVar = 12345;
```
### User defined constants
User defined constants are set as upper case.
**Correct**
```
define('MY_VAR', 'My constant string value');
```
**Incorrect**
```
define('my_var', 'My constant string value');
```
### PHP constants
These types of constant (true,false,null) are set as lower case
**Correct**
```
$my_var = true;
```
**Incorrect**
```
$my_var = TRUE;
```
### HTML / CSS rules
Class names and id's should be hyphenated and not use an underscore
**Correct**
```
class="my-class"
```
**Incorrect**
```
class="my_class"
```
### PHP Coding Standards Fixer
Ensure your code adheres to the project's standards effortlessly by utilizing [PHP Coding Standards Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer). The provided configuration allows for automatic code formatting.
If your IDE doesn't already integrate with php-cs-fixer, run it as a standalone tool:
Use the following command to apply code adjustments and align it with the project's Code Standard:
```
php tools/php-cs-fixer.phar fix -v
```
Integrating php-cs-fixer into your workflow ensures consistent code formatting, streamlining collaboration and maintaining a clean, standardized codebase.
### Static Code Analysis
To preempt common coding mistakes, the code undergoes thorough analysis with the [PHPStan](https://phpstan.org/) code analyzer. If your IDE does not have native integration with PHPStan, you can use it as a standalone tool:
Initiate the following command to analyze your code changes and identify any potential issues:
```
php tools/phpstan.phar
```
Leveraging PHPStan enhances code quality by detecting errors and inconsistencies early in the development process. This proactive approach aids in maintaining a robust and error-free codebase.
# Database Schema
You can download a PDF of the database schema below.
{% file src="/files/vNAgl9EM2DLky6GDoby0" %}
{% file src="/files/p0LQ5RHdNFTgdf8z8GkP" %}
# Extensions
### Create your own extensions
OpenCart supports extensions to add or modify functionality without altering core files. Extensions can include modules (e.g., for adding features like sliders or analytics), payment gateways, shipping methods, themes, reports, and more. In OpenCart 4.x, extensions leverage the MVC-L (Model-View-Controller-Language) pattern, the Events system for hooks, and OCMOD for modifications. This guide provides a step-by-step approach to creating, packaging, and installing extensions, focusing on modules as a common example.
### Prerequisites
* A working installation of OpenCart 4.x.
* Basic knowledge of PHP, HTML, CSS, JavaScript, and the MVC pattern.
* Familiarity with Twig templating (used for views).
* Access to the admin panel and file system (via FTP or server access).
* Tools like a code editor (e.g., VS Code, Notepad++) and ZIP archiver.
Ensure your extension follows OpenCart's naming conventions: filenames should be 1-128 characters, end in `.ocmod.zip` for installable packages, and not exceed 32 MB.
### Types of Extensions
Possible extensions types are:
* **Modules**: Add features like banners, carousels, or custom pages.
* **Feeds:** Product feeds (e.g., Google Merchant)
* **Payments/Shipping**: Integrate gateways (e.g., PayPal) or methods (e.g., UPS).
* **Themes**: Customize the storefront appearance.
* **Reports/Analytics**: Generate insights or integrate tools like Google Analytics.
* **Others**: Anti-fraud, captcha, order totals, etc.
All extensions are managed via the admin panel under **Extensions > Extensions**.
### Directory Structure
Extensions in OpenCart 4.x are packed in a zip file named for example `test_module.ocmod.zip`, once that zip package uploaded into extension installer a folder will be created into the `extension/` directory based on the name of your file, in this case it will be `extension/test_module/`.
The zip package must be structured as follows:
* **install.json**: Metadata file (required for installation).
* **admin/**: Backend files.
* `controller/module/test_module.php`: Admin controller.
* `language/en-gb/module/test_module.php`: Language strings.
* `view/template/module/test_module.twig`: Admin view.
* `model/module/test_module.php`: Optional model for custom DB operations.
* **catalog/**: Frontend files.
* `controller/module/test_module.php`: Frontend controller.
* `language/en-gb/module/test_module.php`: Language strings.
* `view/theme/default/template/module/test_module.twig`: Frontend view (use `default` or theme name).
* `model/module/test_module.php`: Optional model.
* **ocmod/**: Optional, for OCMOD modifications (e.g., `test_module.ocmod.xml`).
Default extensions are in `extension/opencart/`. Make sure to use unique name on your package .ocmod.zip to avoid conflicts (e.g., prefix with your brand).
### Step-by-Step: Creating a Simple Module Extension
Let's create a sample module called "Test Module" that will use events to trigger an action on adding a product to cart.
#### Create the folder
Create a folder named `Test module/`, inside this folder you will create the files as described below.
#### 1. Create the install.json File
This JSON file provides extension metadata.
```json
{
"name": "Test Module",
"version": "1.0",
"author": "Your Name",
"link": "https://yourwebsite.com",
}
```
#### 2. Create the Admin Controller
File: `admin/controller/module/test_module.php`
This handles the admin interface, form saving, and event registration during installation.
```php
load->language('extension/test_module/module/test_module');
$this->document->setTitle($this->language->get('heading_title'));
$data['breadcrumbs'] = [];
$data['breadcrumbs'][] = [
'text' => $this->language->get('text_home'),
'href' => $this->url->link('common/dashboard', 'user_token=' . $this->session->data['user_token'])
];
$data['breadcrumbs'][] = [
'text' => $this->language->get('text_extension'),
'href' => $this->url->link('marketplace/extension', 'user_token=' . $this->session->data['user_token'] . '&type=module')
];
$data['breadcrumbs'][] = [
'text' => $this->language->get('heading_title'),
'href' => $this->url->link('extension/test_module/module/test_module', 'user_token=' . $this->session->data['user_token'])
];
$data['save'] = $this->url->link('extension/test_module/module/test_module.save', 'user_token=' . $this->session->data['user_token']);
$data['back'] = $this->url->link('marketplace/extension', 'user_token=' . $this->session->data['user_token'] . '&type=module');
$data['module_test_module_status'] = $this->config->get('module_test_module_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/test_module/module/test_module', $data));
}
public function save(): void {
$this->load->language('extension/test_module/module/test_module');
$json = [];
if (!$this->user->hasPermission('modify', 'extension/test_module/module/test_module')) {
$json['error'] = $this->language->get('error_permission');
}
if (!$json) {
// Setting
$this->load->model('setting/setting');
$this->model_setting_setting->editSetting('module_test_module', $this->request->post);
$json['success'] = $this->language->get('text_success');
}
$this->response->addHeader('Content-Type: application/json');
$this->response->setOutput(json_encode($json));
}
public function install(): void {
// Load the event model
$this->load->model('setting/event');
// Register the event
$this->model_setting_event->addEvent([
'description' => 'Test module - Event before cart add',
'code' => 'test_module_cart_add_before', // Event code (unique identifier)
'trigger' => 'catalog/controller/checkout/cart.add/before', // Event trigger
'action' => 'extension/test_module/events.onCartAddBefore', // Listener method
'status' => 1,
'sort_order' => 1
]);
}
public function uninstall(): void {
// Remove the event on uninstall
$this->load->model('setting/event');
$this->model_setting_event->deleteEventByCode('test_module_cart_add_before');
}
```
#### 3. Create the Admin Language File
File: `admin/language/en-gb/module/test_module.php`
```php
File: `admin/view/template/module/test_module.twig`
```twig
{{ header }}{{ column_left }}
{{ footer }}
```
#### 5. Create the Frontend Event Controller
File: `catalog/controller/events.php`
This listens to events and will log an entry when it has been triggered.
When the current event does have `$output`, it's possible alter it to change the final rendering.
```php
log->write('onCartAddBefore() has been successfully triggered!');
}
}
```
#### 6. Optional: Add Models if Needed
For custom database operations, create `admin/model/module/test_module.php` or `catalog/model/module/test_module.php`. Extend `\Opencart\System\Engine\Model` and define methods like `addData()` with SQL queries.
#### 7. Using OCMOD for Core Modifications (If Events Are Insufficient)
For modifications not covered by events, use OCMOD XML files in `ocmod/test_module.ocmod.xml`. Example to add a menu item in admin:
```xml
Example OCMOD
example_ocmod
1.0
Your Name
'test-module',
'icon' => 'fas fa-cog',
'name' => 'Test Module',
'href' => $this->url->link('extension/test_module/module/test_module', 'user_token=' . $this->session->data['user_token']),
'children' => []
];
]]>
```
### Packaging and Installation
1. Zip the files in your extension folder (e.g., `test_module.ocmod.zip`), including `install.json` and all subfolders/files. Note that you must not zip the folder `Test module/` but the inside files directly (so when you open your zip file you will see `install.json`, `admin/`, `catalog/`).
2. Go to **Extensions > Installer** > Upload the ZIP.
3. Click on install button near the new entry that appeared in `Extensions > Installer`.
4. Install via **Extensions > Extensions > Modules** (click Install).
5. If you have an ocmod, refresh modifications in **Extensions > Modifications** > Refresh (blue button).
6. Clear cache in **Dashboard > Gear Icon > Clear Cache**.
7. Configure and enable the module in **Extensions > Extensions > Modules**.
If errors occur, check logs in `system/storage/logs/` or ensure no file conflicts.
### Best Practices
* **Namespace Usage**: Always use namespaces (e.g., `Opencart\Admin\Controller\Extension\MyExtension\Module`).
* **Internationalization**: Use language files for all text.
* **Security**: Validate inputs, check permissions (`$this->user->hasPermission()`).
* **Compatibility**: Test on multiple themes and PHP versions (8.1+ recommended).
* **Cleanup**: Implement `uninstall()` to remove DB entries/events.
* **Documentation**: Include instructions in `install.json` or a README.
* **Avoid Core Changes**: Prefer events over OCMOD when possible.
* **Testing**: Use a development store; clear caches frequently.
* **Marketplace Ready**: If distributing, ensure compliance with OpenCart's extension standards.
### More Examples
Current example is basic and will help to understand the logic for extension creation, then to go further and see how are made all extension types (modules, payment gateways, shipping methods, etc) the best is to check the opencart example packages that are included by default.
On default install go to `Extension > Installer`, you will see the following items:
* **OpenCart Language Example**
* **OpenCart OCMOD Example**
* **OpenCart Payment Example**
* **OpenCart Theme Example**
These are specifically made to show how to create an extension of each of these types, there is also :
* **OpenCart Default Extensions**
This one contains various default opencart modules (bestsellers, latest, carrousel, etc), payment gateways (bank transfer, checkout on delivery), and others that will give you practical example of extensions, you can find the zip packages into `storage/marketplace/`folder so you can extract them to see the structure and adapt for you own usage.
# Events
### Introduction
OpenCart v4.x uses an **event system** to allow developers to extend and modify core functionality without altering the core codebase. The event system enables you to hook into specific points in the application lifecycle, execute custom code, and modify data or behavior. This guide explains how to work with events in OpenCart, including registering, triggering, and handling events, with practical examples.
### What is the Event System?
The event system in OpenCart is based on a publisher-subscriber model. Events are triggered at specific points in the application, and developers can register listeners (handlers) to execute custom code when these events occur. This makes OpenCart highly extensible, allowing modifications like adding custom logic, altering data, or integrating third-party services.
#### Key Components
* **Event**: A named trigger point in the code (e.g., `catalog/controller/product/category/before`).
* **Listener**: A function or method that executes when an event is triggered.
* **Event Registry**: The system that maps events to their listeners.
* **Trigger**: The action of firing an event to execute registered listeners.
### Event Naming Convention
Events are typically identified by a string key in the format `namespace/action/stage`.
* **Namespace**: Indicates the context (e.g., `catalog`, `admin`, `extension`).
* **Action**: Specifies the action path (e.g., `controller/checkout/cart.add`).
* **Stage**: Indicates when the event occurs (`before` or `after`).
Example: `catalog/controller/product/product/before` is triggered before rendering the product view page in the catalog (front-end). Note that when referring to index method you have to let the action path without specifying the method (correct: product/product, wrong: product/product.index).
#### Common Events
Here are some commonly used events you might want to hook into:
* `catalog/view/product/product/before`: Before rendering a product page.
* `catalog/view/common/content_top/after`: After rendering content\_top.
* `catalog/controller/checkout/cart.add/after`: After adding a product to the cart.
* `catalog/model/checkout/order.editOrder/before`: Before editing an order.
* `catalog/controller/checkout/confirm/after`: After confirming a checkout.
### How to Register an Event Listener
Event listeners are registered in OpenCart through the **event registry**. You typically define listeners in your module or extension's code, either in a custom module or by modifying an existing extension.
#### Steps to Register an Event Listener
1. **Create a Listener Method**: Write the function or method that will handle the event.
2. **Register the Event**: Map the event to the listener using the event registry.
3. **Ensure Accessibility**: Ensure the listener is loaded when the event is triggered.
#### Example: Registering an Event Listener
Suppose you want to execute custom code before a product is added to the cart in the front-end (`catalog/controller/checkout/cart.add/before`).
**Step 1: Create the Listener**
Create a PHP class for your extension. For example, place the following code in `extension/test_module/catalog/controller/events.php`:
```php
log->write('onCartAddBefore() has been successfully triggered!');
}
}
```
**Step 2: Register the Event**
Events are typically registered in the `install()` method of your extension. For programmatic registration, use the `startup/event` model.
Add the following code to your module’s controller:
```php
load->model('setting/event');
// Register the event
$this->model_setting_event->addEvent([
'description' => 'Test module - Event before cart add',
'code' => 'test_module_cart_add_before', // Event code (unique identifier)
'trigger' => 'catalog/controller/checkout/cart.add/before', // Event trigger
'action' => 'extension/test_module/events.onCartAddBefore', // Listener method
'status' => 1,
'sort_order' => 1
]);
}
public function uninstall(): void {
// Remove the event on uninstall
$this->load->model('setting/event');
$this->model_setting_event->deleteEventByCode('test_module_cart_add_before');
}
}
```
**Step 3: Test the Event**
* Install your module via the OpenCart admin panel (`Extensions > Installer`).
* Install and enable your module in `Extensions > Extensions` (if config code "module\_\[module\_name]\_status" is not set then the corresponding event won't be triggered).
* Add a product to the cart in the front-end.
* Check the log file (`System > Maintenance > Error logs`) to verify that your custom log message appears.
### Triggering Custom Events
You can also trigger your own custom events. This is useful for custom modules or extensions that need to notify other parts of the system.
Suppose you want to trigger a custom event called `extension/test_module/custom_action/after`.
In your controller or model, use the `trigger()` method from the event registry. For example, in `/extension/test_module/catalog/controller/custom_action.php`:
```php
// Data to pass to event
$data = ['message' => 'Custom action executed'];
// Trigger a custom event
$this->event->trigger('extension/test_module/custom_action/after', $data);
```
### Best Practices
1. **Use Descriptive Event Names**: Follow the `namespace/action/stage` convention for clarity.
2. **Avoid Core Modifications**: Use the event system or OCMOD to keep your code upgrade-safe.
3. **Handle Data Carefully**: Always validate and sanitize data passed to event listeners.
4. **Optimize Performance**: Avoid heavy processing in event listeners to prevent slowing down the application.
5. **Test Thoroughly**: Test your event listeners in different scenarios to ensure they work as expected.
6. **Clean Up on Uninstall**: Always remove events in the `uninstall()` method to avoid orphaned entries.
### Debugging Events
* **Check Logs**: Enable error logging in OpenCart (`System > Settings > Server > Error Logging`) to debug issues.
* **Verify Event Registration**: Ensure your event is registered in `Extensions > Events`.
* **Test Incrementally**: Test one listener at a time to isolate issues.
# Startups
### Introduction
The **startup system** allow developers process code at very early stage when opening a page, it is useful for example to initialize some library for further use, handle seo related data, etc. This guide explains how to work with startups in OpenCart with practical examples.
#### Key Components
* **Startup class**: The class to execute at startup.
* **Startup registry**: The system that stores the startups.
### How to Register a Startup
1. **Create a startup class**: Write your code into the index() method.
2. **Register the startup**: Save your startup using the startup registry.
3. **Ensure accessibility**: Ensure the startup is loaded when accessing a page.
#### Example: Registering a Startup
**Step 1: Create the Startup Class**
Create a PHP class for your extension. For example, place the following code in `extension/test_module/catalog/controller/startup.php`:
```php
log->write('My startup has been successfully initialized!');
}
}
```
**Step 2: Register the Startup**
Startups are typically registered in the `install()` method of your extension. For programmatic registration, use the `setting/startup` model.
Add the following code to your module’s controller:
```php
load->model('setting/startup');
// Register the startup
$this->model_setting_startup->addStartup([
'code' => 'my_startup',
'action' => 'catalog/extension/test_module/startup',
'description' => 'My custom startup',
'sort_order' => 1,
'status' => true
]);
}
public function uninstall(): void {
// Remove the startup on uninstall
$this->load->model('setting/startup');
$this->model_setting_startup->deleteStartupByCode('my_startup');
}
}
```
**Step 3: Test the Startup**
* Install your module via the OpenCart admin panel (`Extensions > Installer`).
* Install your module in Extensions menu (`Extensions > Extensions`).
* Check if the startup has been correctly registered into `Extensions > Startups`.
* Open a page on front-end
* Check the log file (`System > Maintenance > Error logs`) to verify that your custom log message appears.
# Tasks
### Introduction
Tasks have been introduced in OpenCart v4.2, they are background processes for tasks that does not require immediate feedback, aiming to speed up the whole experience.
Tasks are run in a background process using PHP shell\_exec() function, which may overcome some server limitations while using normal PHP process.
### How to Create a task
* **Create a task class**: Write your code into the index() method.
* **Register the task**: Save your task using the task registry.
* **Ensure Accessibility**: Ensure the task is correctly working.
#### Example
**Step 1: Create the Task Class**
Create a PHP class for your extension. For example, place the following code in `extension/test_module/catalog/controller/task.php`:
```php
log->write('My task has successfully started!');
}
}
```
**Step 2: Register the Task**
Tasks are typically registered in the `install()` method of your extension.
Add the following code to your module’s controller:
```php
load->model('setting/task');
// Register the task
$task_data = [
'code' => 'my_task',
'action' => 'task/catalog/test_module.task',
'args' => []
];
$this->model_setting_task->addTask($task_data);
}
public function uninstall(): void {
// Remove the task on uninstall
$this->load->model('setting/task');
$this->model_setting_task->deleteTaskByCode('my_task');
}
}
```
**Step 3: Test the Task**
* Install your module via the OpenCart admin panel (`Extensions > Installer`).
* Install your module in Extensions menu (`Extensions > Extensions`).
* Open `Extension > Tasks`, you should see your new entry
* Click on the button `▶️ Run Tasks`
* Check the log file (`System > Maintenance > Error logs`) to verify that your custom log message appears.
# Cron Jobs
### Introduction
This guide provides detailed instructions for developers on setting up and managing cron jobs in OpenCart. Cron jobs are essential for automating recurring tasks such as refreshing currency rates, cache clearing, sitemap generation, sending newsletters, etc.
OpenCart integrates a cron handler that can centralize all reccuring tasks to allow to easily manage all from the admin instead of having to manage them from the host panel, which can be convenient for the end-user.
### Set up the OpenCart Cron in your Host Panel
First of all it's necessary to set up your host to call the OpenCart cron handler, this is necessary only once, then all will be handled directly from OpenCart, follow this procedure to set up the cron, here based on cPanel but the same can be done in all host panels.
1. Open `Extension > Cron` menu
2. Go to your cPanel Cron jobs section (or equivalent in other host panels)
3. Add new cron job
4. copy-paste the command that is displayed into `Extension > Cron` (e.g.: `wget "https://mywebsite.tld/index.php?route=cron/cron" --read-timeout=5400`)
5. Set the cron task to run every hour
That's all, now all the cron tasks set into `Extension > Cron` will run automatically.
### How to Create an OpenCart Cron Job
1. **Create a cron class**: Write your code into the index() method.
2. **Register the cron job**: Save your cron job using the cron registry.
3. **Ensure Accessibility**: Ensure the cron is correctly working.
#### Example
**Step 1: Create the Cron Class**
Create a PHP class for your extension. For example, place the following code in `extension/test_module/catalog/controller/cron.php`:
```php
log->write('My cron job has successfully started!');
}
}
```
**Step 2: Register the Startup**
Startups are typically registered in the `install()` method of your extension. For programmatic registration, use the `Startup` model.
Add the following code to your module’s controller:
```php
load->model('setting/cron');
// Register the cron job
$this->model_setting_cron->addCron([
'code' => 'my_cron', // Cron code (unique identifier)
'description' => 'My custom cron',
'cycle' => 'day', // cycle (hour, day, week)
'action' => 'extension/test_module/cron', // action
'status' => true
]);
}
public function uninstall(): void {
// Remove the cron job on uninstall
$this->load->model('setting/cron');
$this->model_setting_cron->deleteCronByCode('my_cron');
}
```
**Step 3: Test the Cron Job**
* Install your module via the OpenCart admin panel (`Extensions > Installer`).
* Install your module in Extensions menu (`Extensions > Extensions`).
* Open `Extension > Cron Jobs`, you should see your new entry
* Click on the button `▶️ Run Cron Job`
* Check the log file (`System > Maintenance > Error logs`) to verify that your custom log message appears.