With RAD: handlers and kernel overrides #

Tutorial 8. Two wizards change system behavior beyond your own code: the Handler extension wizard (/setup/handlerextension/<kind>) writes a class the system uses in place of its default, chosen by one setting, and the Kernel override wizard (/setup/kerneloverride) writes the last resort, a replacement of a kernel class. The output below was produced by the wizards' generators (expHandlerWizard::files(), expKernelOverrideWizard::files()); every PHP file passed php -l.

Part A: a mail transport #

1. The form #

Open /setup/handlerextension/mail. The page explains the kind from the wizard's recipe: "How mail leaves the system. The default hands mail to php, which hands it to the machine. A transport of your own can send it through an api, queue it, or write it to disk on a machine that must not send anything." It names the base class (eZMailTransport, lib/ezutils/classes/ezmailtransport.php) and the setting (site.ini [MailSettings] TransportAlias).

2. The files #

.gitignore
LICENSE
README.md
classes/mysitelogmailtransport.php
composer.json
doc/examples.php
extension.xml
ezinfo.php
settings/site.ini.append.php

[MailSettings]
TransportAlias[mysitelog]=mysiteLogMailTransport

class mysiteLogMailTransport extends eZMailTransport
{
    /**
     * Sends one mail and says whether it went. Returning false is how a
     * failure is reported; nothing else is read.
     */
    public function sendMail( eZMail $mail )
    {
        // Not written yet. Returning true keeps the system
        // working the way it did before this handler was switched on.
        return true;
    }
}

3. Write it, then select it #

Replace the body with the logging transport of Handlers named by settings. The wizard's recipe note matters: "Set Transport in the same section to the alias, or the default is still used." Set it on the development server only:

./console exp:ini set site.ini/MailSettings/Transport mysitelog global

Part B: a kernel override #

1. The form #

Open /setup/kerneloverride. Name the kernel class to replace and, required, the reason: why nothing lighter works. The wizard refuses a class that something already overrides ("Two overrides of one class do not combine").

2. The files #

For eZSection:

.gitignore
LICENSE
README.md
bin/checkdrift.php
composer.json
extension.xml
ezinfo.php
kernel_override/ezsection.php

The copy starts with a header that records its provenance:

 * ##  KERNEL OVERRIDE - this file replaces a kernel class                  ##
 *
 * eZSection, copied from
 *
 *     kernel/classes/ezsection.php
 *     md5 <checksum of the kernel file when copied>
 *     copied <date>

followed by the reason and "What you have taken on": "This is not a subclass. There is no parent to call and nothing is inherited". bin/checkdrift.php compares the kernel file with that checksum after every upgrade.

3. Switching it on #

The generated README lists the steps: activate the extension; allow overrides in config.php with define( 'EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE', true );; generate the override map with php bin/php/ezpgenerateautoloads.php -o; clear the caches. Then run the drift check in every deployment.

Read Kernel class overrides: the last resort before you use this.

Related pages #

• Previous: With RAD: a settings-only extension
• Next: By hand: the smallest extension in five minutes
• Handlers named by settings
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.