Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Kernel class overrides: the last resort

Replacing a kernel class through the override autoload map: how it works, what it costs, the wizard and its drift check, and the lighter mechanisms to try first.

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/extension-development/part-3-extension-developer/kernel-overrides-the-last-resort.md

On this page

Kernel class overrides: the last resort

Part 3, chapter 30. When nothing else reaches the behavior you must change, an extension can replace a kernel class with its own copy, under the same name. It works, and it is the most expensive thing you can do to an installation. This chapter explains how it works and why you should avoid it.

How it works

  1. config.php allows overrides: define( 'EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE', true ); (config.php-RECOMMENDED ships it commented out, false).
  2. Your extension holds a file that declares the kernel class, for example extension/mysite_override/kernel_override/ezcontentobjecttreenode.php declaring class eZContentObjectTreeNode.
  3. php bin/php/ezpgenerateautoloads.php -o writes var/autoload/ezp_override.php, a map of the classes your extensions declare that the kernel also declares.
  4. The autoloader (autoload.php) merges that map over the kernel's when the constant is true, so your file is loaded instead of the kernel's.

What it costs

The kernel override wizard's README says it plainly: "An override is not a subclass. There is no parent to call and nothing is inherited: this file is the class as far as the rest of the system is concerned." So:

  • every fix the kernel makes to that class after you copied it is a fix your site does not get, until someone notices,
  • two extensions overriding the same class do not combine; whichever the generator finds last wins, silently,
  • an upgrade can change what other classes expect from it, and your copy breaks without a sign until it is used.

The wizard

Setup > RAD > Kernel override (/setup/kerneloverride, kernel/setup/expkerneloverridewizard.php) writes the override as a complete extension: the copy in kernel_override/, a README, and bin/checkdrift.php, which compares the kernel's current file with the one that was copied. Run it after every upgrade:

php extension/<name>/bin/checkdrift.php

Exit status 0 means the kernel file is unchanged, 1 that it changed and someone must decide which changes the override needs, 2 that the file is gone. The wizard refuses to write a second override of a class that is already overridden.

Before you do it

The wizard's README ends with the right advice: "Almost everything in this system has a lighter way in - a handler named by a setting, an event listener, a filter, a template override." In order of preference:

Instead of overridingTry
a templatea template override (Template overrides: the basics)
a mail, login, session, search ... classa handler (Handlers named by settings)
behavior around publishing, caches, outputan event listener or filter (Events, listeners and filters)
a kernel module's viewa view re-implementation (site.ini [RunnableSettings] Implementation[]) or an extension module that replaces the module (An extension can replace a kernel module)
a datatype's behavioryour own datatype
a bug in the kernela pull request to the kernel (Contributing back with pull requests)

A fix sent upstream helps everyone and costs you nothing at the next upgrade. An override is the answer only for the time it takes the fix to be released, and should then be removed.

Seeing overrides

The RAD survey (/setup/radsurvey) counts "kernel classes replaced" on an installation, and eZpedia's "Overriding kernel classes within an extension" describes the mechanism from the earlier years.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x