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).
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>
versionis required. The current kamod version is1.0.- The
changessection can contain severaloperationnodes. They are applied in order. - Only the
replaceoperation 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 theU,mandsmodifiers (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.login 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 tokamod.errors.logtoo, the patch is not applied and the file stays unchanged. - The number of lines in
kamod.errors.logis shown on the ambulance icon in the admin header.