Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 27 ยท Events and OCMOD

OCMOD Modifications

Learn how OCMOD patches OpenCart files at runtime with install.xml: search and add operations, regex, the log, refresh, conflicts and when to prefer events.

Events cover most extension needs, but not all of them. Sometimes the core has no hook at the place you need: a line in a template, a condition inside a long method, a column in an admin list. For those cases OpenCart has OCMOD, short for OpenCart Modification. An OCMOD is an XML file that describes small text edits ("find this line, add that line after it") which OpenCart applies to a copy of the target files. Your original core files stay untouched.

OCMOD is powerful and fragile. It works by matching text, so a core update that rewords one line can silently break it, and two modifications that target the same text can fight. In this lesson you will learn the install.xml format, how the edits are applied and logged, how to deal with conflicts, and when not to use OCMOD at all. The XML here is read-only, because it needs a running store; the runnable examples are a plain-PHP patch engine that follows the same ideas. Read Events first, because an event should be your first choice.

The shape of install.xml

An OCMOD file is an XML document placed at the root of your .ocmod.zip package as install.xml. It starts with some metadata, then lists files and operations:

XML
<?xml version="1.0" encoding="utf-8"?>
<modification>
    <name>Acme Free Shipping Notice</name>
    <code>acme_free_shipping_notice</code>
    <version>1.0.0</version>
    <author>Acme</author>
    <link>https://example.com</link>

    <file path="catalog/view/template/product/product.twig">
        <operation error="log">
            <search><![CDATA[<h1>{{ heading_title }}</h1>]]></search>
            <add position="after"><![CDATA[
<p class="text-success">Free shipping over $50</p>]]></add>
        </operation>
    </file>
</modification>

The pieces:

  • <code> is the unique identifier. It is required, and installing a second modification with the same code replaces the first. Use a vendor prefix.
  • <file path="..."> names the file to change, relative to the store root. A path can contain a wildcard such as catalog/controller/product/*.php, and a comma-separated list of paths is also possible, but narrow paths are safer.
  • <operation> is one search-and-add pair. A file can have many operations; they run in order, each on the result of the previous one.
  • <search> is the text to find. It is matched against the file contents.
  • <add position="..."> says what to do with the match: after and before insert the new text next to the matched code, and replace swaps the match for the new text. The offset attribute moves the insertion point by a number of lines, and trim="false" keeps surrounding whitespace.

Use CDATA sections for code so characters like < and & do not need escaping. OCMOD processes files in a line-oriented way, so the text you search for should be a clear, ideally whole-line fragment. Check your result in the generated file rather than assuming.

Search options: index, limit and regex

If the search text occurs several times in a file, OCMOD by default applies your edit to every occurrence. The <search> element has attributes to control this:

  • index="2" applies the operation only to the second occurrence (counting from 1). You can give a comma-separated list such as index="1,3".
  • limit="1" stops after that many replacements.
  • regex="true" treats the search text as a regular expression, written with delimiters, for example <search regex="true"><![CDATA[~\$data\['price'\] = .*;~]]></search>. Regex can match varying text but is much easier to get wrong and to make too greedy.

And on the <operation> and <file> you can set error to say what happens when the search text is not found:

Value Effect
log Write a line to the modification log and continue (the usual choice)
skip Ignore silently and continue
abort Stop processing this file (later operations on it are not applied)

Prefer log. A silent skip hides the fact that a core update broke your modification, and abort can leave a feature half-working.

How OCMOD applies the changes

When you press Refresh on the Modifications page, OpenCart does the following:

  1. It deletes the previously generated copies in the storage modification folder.
  2. It reads the XML of every enabled modification from the database.
  3. It copies each target file and applies the operations in order.
  4. It writes the changed copies into storage/modification/, mirroring the original path.
  5. It records every success and failure in the modification log.

At runtime, OpenCart's file loading prefers the copy in storage/modification/ when it exists. That is why you must press Refresh after installing, uninstalling or enabling a modification, or nothing changes. It is also why a modification only affects files that OpenCart loads through this mechanism, which means PHP classes and Twig templates, not plain JavaScript or CSS files that the web server serves directly.

flowchart LR
    A["Core file<br/>product.twig"] --> C["Refresh"]
    B["install.xml<br/>operations"] --> C
    C --> D["Patched copy in<br/>storage/modification/"]
    C --> E["Log: found or<br/>not found"]
    D --> F["Used when the<br/>page is rendered"]

Refresh builds patched copies and a log. The original core file is never edited.

The log is your best friend

Open the log (the Log button on the Modifications page) after every refresh. For each operation it reports whether the search text was found. Typical messages include "NOT FOUND" for a search that did not match and "MISSING FILE" for a path that does not exist. If a feature stops working after a core update, the log tells you which operation lost its anchor. Always read it before blaming anything else, and clear it afterwards so the next problem is easy to spot.

Conflicts

OCMOD conflicts come in three forms:

  1. Same anchor. Two modifications search the same line. If the first one replaces it, the second will no longer find its text, and its edit is lost. If both only add after the line, both work, but their order depends on the modification names, which is hard to control.
  2. Overlapping changes. One modification inserts a line in the middle of a block that another modification searches as a multi-line pattern. The pattern no longer matches.
  3. Core upgrades. The upstream text changes, and all operations anchored on it start failing.

Defences: prefer before and after over replace, anchor on short stable lines rather than long blocks, keep operations few and small, always set error="log", and write down the OpenCart versions you tested on. Never anchor on a line another extension is likely to change, like the output of a popular module.

OCMOD or events?

Event OCMOD
Needs a hook in the core Yes No, any text will do
Survives a core update Usually Only if the anchor text stays
Visible to other extensions Ordered by sort_order Hidden conflicts
Can change a line inside a method No Yes
Cost Small run-time call Refresh, extra files

Use OCMOD as the last resort. If an event can do the job, even with a slightly clumsier solution, the event will break less. Typical good uses of OCMOD are inserting one line into an admin list template, adding a column in an admin table, or changing a condition inside a method where no event fires. Document each OCMOD you ship, explain why an event was not enough, and test it on the lowest and highest version you support. Packaging details are in Packaging, Marketplace and Upgrades.

Try it: a patch engine

This stand-in is not OpenCart's modification class. It applies a list of operations (the same ideas as search, add, index, regex and error) to text, and writes a log. It works on an array instead of XML so it can run anywhere.

PHP Applying search and add operations

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 first two operations find their anchors, the third uses index to touch only the second line that contains <p, and the last does not find its anchor, so the log records "NOT FOUND" and the file is otherwise unchanged. That log line is exactly what you would read on the Modifications page.

The engine above is intentionally simple. The next example shows the central danger, a conflict between two modifications on the same anchor, and how a regex search matches varying text.

PHP Conflicts and regex searches

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.

When both modifications replace the same line, the second logs NOT FOUND and its change is lost. Anchoring on stable lines and adding next to them is the safer pattern.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does OCMOD put the patched version of a core file?

    OCMOD applies operations to copies stored in storage/modification, which OpenCart prefers when loading files. The original core file is never edited.
  2. 2. You installed an OCMOD but nothing changed on the storefront. What is the first thing to try?

    Patched copies are built when you refresh. The log then tells you whether each search text was found.
  3. 3. Which error setting is usually best on an operation, and why?

    With log, a failed search is recorded and the rest continues. Silent skipping hides breakage after a core update.
  4. 4. When should you choose OCMOD over an event?

    Events are more stable. OCMOD is the last resort for changes inside code where the core offers no hook.

Summary

  • OCMOD is an install.xml file at the root of the package that describes search-and-add edits applied to copies of files.
  • Operations use <search> (with index, limit, regex) and <add position="before|after|replace">.
  • Press Refresh after installing, uninstalling or enabling, and always read the modification log.
  • Set error="log" so a lost anchor is recorded instead of hidden.
  • Conflicts arise from shared anchors and overlapping changes; prefer short stable anchors and adding next to them.
  • Use events first and OCMOD only when no hook exists.

Next, build a reusable, configurable widget in Modules and Layouts.