Registration order and overrides
Operator names are global: one name, one class, for every template of a siteaccess. When two autoload files
register the same name, the template engine has rules for which one serves it, and one of those rules is
surprising. This page explains them from lib/eztemplate/classes/eztemplate.php and shows them on a development installation. For the
practical "how do I replace a kernel operator", see Overriding kernel operators.
Contents
- The order the files are read
- The last registration wins
- The names registered twice
- A loaded class takes its names back
- Compiled templates
- Functions and fetch functions
- Rules
The order the files are read
eZTemplate::factory() builds the list of folders to read from two site.ini settings and then calls
autoload(), which includes eztemplateautoload.php from each folder in that order:
[TemplateSettings] AutoloadPathList[]: insettings/site.inithe template library (lib/eztemplate/classes/), the kernel (kernel/common/),lib/ezpdf/classes/andkernel/private/eztemplate/;[TemplateSettings] ExtensionAutoloadPath[]: one entry per extension, expanded toextension/<name>/autoloads/. Each extension adds its own line in itssettings/site.ini.append.php, so the order is the order in which the INI system merges those files, which follows the order of[ExtensionSettings] ActiveExtensions[](and of the siteaccess'sActiveAccessExtensions[]).
On the site siteaccess the engine reads 23 files: the four above, then
bcwebsitestatistics, ezwt, ezwebin, ezoe, eztags, ezstarrating, ezurlmultisite, sevenx_themes_media, powercontent, recaptcha, explayouts_ui, explayouts, enhancedezbinaryfile, swark, owsimpleoperator, cjw_newsletter, xrowmetadata, ezjscore, expui (bcwebsitestatistics adds its folder to AutoloadPathList[] itself, the others use
ExtensionAutoloadPath[]). The admin siteaccess reads more (extension expai adds its operators there), so the same name
can be served by different classes on different siteaccesses.
The last registration wins
Each file sets $eZTemplateOperatorArray, a list of entries like
$eZTemplateOperatorArray[] = array( 'script' => 'extension/myext/autoloads/myoperators.php',
'class' => 'myOperators',
'operator_names' => array( 'my_one', 'my_two' ) );and registerAutoloadOperators() stores the entry under each name: $this->Operators[$operatorName] = $operatorDefinition;.
A later file that names the same operator simply overwrites the entry. Nothing warns about it.
At this point nothing is loaded: the engine only knows which class to load for a name. The class file is included
and the object created the first time a template uses one of its names (loadAndRegisterOperators()).
The names registered twice
This short script lists every name that more than one file registers, with the classes in reading order (save it
anywhere and run it with php bin/php/ezexec.php -s site <file>):
// Which eztemplateautoload.php registers each operator name, in the order the engine reads them.
$owners = array();
foreach ( eZTemplate::factory()->autoloadPathList() as $path )
{
$eZTemplateOperatorArray = array();
if ( !file_exists( $path . 'eztemplateautoload.php' ) )
continue;
include $path . 'eztemplateautoload.php';
foreach ( $eZTemplateOperatorArray as $definition )
{
$names = isset( $definition['operator_names'] ) ? $definition['operator_names']
: call_user_func( $definition['operator_names_function'] );
foreach ( $names as $name )
$owners[$name][] = $definition['class'] ?? $definition['function'];
}
}
foreach ( $owners as $name => $classes )
if ( count( $classes ) > 1 )
echo str_pad( $name, 20 ), implode( ' -> ', $classes ), "\n";Its output on the site siteaccess:
nl2br eZTemplateNl2BrOperator -> eZPHPOperatorInit
image eZTemplateImageOperator -> sevenxThemesMediaOperators
trim eZTemplateStringOperator -> eZTemplateStringOperator
ltrim eZTemplateStringsOperator -> SwarkLTrimOperator
rtrim eZTemplateStringsOperator -> SwarkRTrimOperator
strip_tags eZTemplateStringsOperator -> eZPHPOperatorInit
strpos eZTemplateStringsOperator -> SwarkStrPosOperator
strrpos eZTemplateStringsOperator -> SwarkStrRPosOperator
substr eZTemplateStringsOperator -> SwarkSubStrOperator
ezurl eZURLOperator -> eZURLMultisiteURLOperator
ezroot eZURLOperator -> eZURLMultisiteURLOperator
ezdesign eZURLOperator -> eZURLMultisiteURLOperator
ezimage eZURLOperator -> eZURLMultisiteURLOperator
exturl eZURLOperator -> eZURLMultisiteURLOperator
ezsys eZURLOperator -> eZURLMultisiteURLOperator
ezhttp eZURLOperator -> eZURLMultisiteURLOperator
ezhttp_hasvariable eZURLOperator -> eZURLMultisiteURLOperator
ezini eZURLOperator -> eZURLMultisiteURLOperator
ezini_hasvariable eZURLOperator -> eZURLMultisiteURLOperator
json_encode SwarkJSONEncodeOperator -> ezjscEncodingTemplateFunctions
str_replace SwarkStrReplaceOperator -> PHPFunctionOperatorThree kinds of overlap show up:
- Deliberate, complete overrides: extension ezurlmultisite replaces all ten names of the kernel's
eZURLOperatorwith a subclass. This is the safe pattern, explained in Overriding kernel operators. - Accidental clashes between extensions and the library: swark registers its own
ltrim,rtrim,strpos,strrpos,substr,json_encodeandstr_replace, the template library and ezjscore register the same names, and the media theme registers its ownimage. These are the dangerous ones, as the next section shows. - Settings-driven names:
nl2br(from cjw_newsletter'stemplate.ini.append.php) andstrip_tags(from ezmultiupload's) are also listed intemplate.ini[PHP] PHPOperatorList[], which the kernel turns into operators served byeZTemplatePHPOperator(created by the functioneZPHPOperatorInit). (trimappears twice in the library's own list; that is the same class.)
A loaded class takes its names back
When the engine loads an operator class, registerOperatorsInternal() registers the object under every name
its operatorList() returns:
foreach( $operatorObject->operatorList() as $operatorName )
{
$this->Operators[$operatorName] = $operatorObject;
}So if a class with many names is loaded after another class took one of those names, it takes the name back,
whatever the autoload order said. Which class serves a clashing name therefore depends on which operators the
request used before. With substr: swark's version treats a length of 0 as "to the end", the library's
eZTemplateStringsOperator passes 0 to PHP, which returns an empty string. Rendered on a development installation with a fresh engine:
['abcdef'|substr( 2, 0 )]Output:
[cdef]The same expression in one template, before and after a use of strlen (an operator of eZTemplateStringsOperator):
['abcdef'|substr( 2, 0 )]
'abc'|strlen
['abcdef'|substr( 2, 0 )]Output:
[cdef]
3
[]The first substr was served by SwarkSubStrOperator (the last registration); strlen loaded
eZTemplateStringsOperator, which registered all its sixty names, substr among them, and the second substr
was served by the library. In a real page the "before" can be any template that ran earlier in the request: the
pagelayout, an included menu, another block. The result of a template can change because a different part of the
page changed.
The same holds for a single overriding name from an extension. An extension that registers only upcase (one of
the fifteen names of eZTemplateStringOperator) wins in the first line and loses after wash, an operator of the
same library class, has run:
'fit & healthy'|upcase
'Fit & Healthy'|wash
'fit & healthy'|upcaseOutput:
[override] FIT & HEALTHY
Fit & Healthy
FIT & HEALTHY(Rendered with the override registered on the engine in memory; the [override] marker only shows which class
answered.) Almost every page uses wash, so such an override would work in a test template and fail on real pages.
Compiled templates
The development installation used here runs with [TemplateSettings] TemplateCompile=enabled, the default. When the compiler meets an operator it
loads the operator's class at compile time to ask for its hints, and with hints it may write the operator's work
straight into the generated PHP (see The operator class interface).
Two consequences:
- the class that is loaded when the template is compiled can decide the result, not the one that would serve
the name at run time. The
upcaseexample above, rendered by the compiler into a scratch folder, givesFIT & HEALTHYin all three lines: the compiler had loadedeZTemplateStringOperatorforwashand used its inline code forupcase; - an override that inherits the library's hints keeps the library's inline code in compiled templates, see Overriding kernel operators.
Functions and fetch functions
Template functions ($eZTemplateFunctionArray) are registered the same way, last registration wins, and a loaded
function class registers all its functionList() names. On a development installation no function name is registered twice.
Fetch functions follow a different rule: fetch( 'content', ... ) uses the first content/function_definition.php
found in the module repositories, and extension repositories are searched before the kernel. See
Fetch functions: how they work.
Rules
- Give every operator a name no other operator has: a prefix of your extension (
exp_,myext_) is the habit. - Before choosing a name, check the operator index and run the script above on every siteaccess that will use it.
- Override a kernel or library operator only by replacing all names of its class with a subclass, as Overriding kernel operators explains.
- Do not rely on
ActiveExtensions[]order to settle a clash between two extensions: it only decides the first registration, and lazy loading can undo it.
Related pages
- Overriding kernel operators
- Registering operators
- The operator class interface
- Operator index
- OW Simple Operator: limitations and risks
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.