Ka Extensions for OpenCart 4

This documentation applies to Ka Extensions for OpenCart 4.x only. It is not compatible with OpenCart 3.

KaPatch Mechanism

Overview

KaPatch makes text changes in files, like OCMOD. It is a part of kamod: patches are applied when the kamod cache is built, the original files are not changed. The patched copies are stored in the kamod cache (system/storage/cache.kamod/ ) together with the classes generated by kamod.

Use kapatch when a file cannot be changed by inheritance (see Overriding Core Files), for example to change a private property to protected or to insert a call of your code into a twig template.

File Structure

Every patched file has its own patch file. It is placed in the kamod directory of the module at the path of the original file with the .xml extension added.

Example

Original file:

system/library/mail.php

Patch file:

extension/my_module/kamod/system/library/mail.php.xml

PHP class files (controllers, models, libraries) and twig templates can be patched, including files of other extensions (kamod/extension/<module>/... ). A PHP file can have patches and child classes at the same time: the patches are applied to the original class first. The same is true for twig templates: the patches are applied to the original template, child templates of modules extend the patched copy.

KaPatch Format

<kapatch version="1.0">
    <changes>
        <operation type="replace">
            <search><![CDATA[SEARCH-STRING]]></search>
            <text><![CDATA[REPLACEMENT-STRING]]></text>
        </operation>
        <operation type="replace">
            <search regexp="true"><![CDATA[REGULAR-EXPRESSION]]></search>
            <text><![CDATA[REPLACEMENT-STRING]]></text>
        </operation>
    </changes>
</kapatch>
  • version is required. The current kamod version is 1.0 .
  • The changes section can contain several operation nodes. They are applied in order.
  • Only the replace operation type is supported.
  • All occurrences of the search string are replaced.
  • With regexp="true" the search string is a regular expression without delimiters. It is used with the U , m and s modifiers (ungreedy, multiline, the dot matches new lines), and / must be escaped. The replacement can contain $1 -style references.

Real examples from Ka Extensions:

<!-- kamod/system/library/mail.php.xml -->
<kapatch version="1.0">
    <changes>
        <operation type="replace">
            <search><![CDATA[private array]]></search>
            <text><![CDATA[protected array]]></text>
        </operation>
    </changes>
</kapatch>
<!-- kamod/admin/view/template/common/header.twig.xml -->
<kapatch version="1.0">
    <changes>
        <operation type="replace">
            <search><![CDATA[<ul class="nav navbar-nav">]]></search>
            <text><![CDATA[<ul class="nav navbar-nav">
                {{ include (dir(_self) ~ 'header/navbar.twig', ignore_missing = true) }}]]></text>
        </operation>
    </changes>
</kapatch>

Errors

  • When the search string of an operation is not found, the error is written to kamod.errors.log in the logs directory, the other operations are applied.
  • An optional operation is marked with skip="true" . When its search string is not found, no error is written:

    <operation type="replace" skip="true">
        <search><![CDATA[optional search]]></search>
        <text><![CDATA[optional replacement]]></text>
    </operation>
  • Errors in the patch file itself (missing file, wrong XML, missing or unsupported version ) are written to kamod.errors.log too, the patch is not applied and the file stays unchanged.
  • The number of lines in kamod.errors.log is shown on the ambulance icon in the admin header.

Best Practices

Avoid inserting large chunks of code with kapatch. Insert a short call of a method or an include of a template of your module, and keep the code there (see Code Design Guidelines).

Search results