events.xml

XML schema: events.xsd · Linking and validation.

events.xml registers package event listeners.

Use it when a package should react to framework events or extension points provided by other packages.

Basic Structure

Create events.xml in the package root.

<?xml version="1.0" encoding="UTF-8"?>
<quiqqer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://www.quiqqer.com/docs/schemas/2.x/events.xsd">
    <events>
        <event on="eventName" fire="\Vendor\Package\EventHandler::method"/>
    </events>
</quiqqer>

The on attribute contains the event name. The fire attribute contains the static PHP method that should be called.

Listener Classes

Event listener methods are usually grouped in an event class.

<?php

namespace Vendor\Package;

class Events
{
    public static function onSiteSave($Site): void
    {
        // React to the event.
    }
}

The listener method signature must match the event that is fired.

Priority

Use priority only when the order between listeners matters.

<event on="eventName"
       fire="\Vendor\Package\Events::method"
       priority="20"
/>

If no priority is set, QUIQQER uses the default priority.

Multiple Listeners

A package can register several listeners.

<quiqqer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://www.quiqqer.com/docs/schemas/2.x/events.xsd">
    <events>
        <event on="onSiteSave" fire="\QUI\Bricks\Events::onSiteSave"/>
        <event on="onSmartyInit" fire="\QUI\Bricks\Events::onSmartyInit"/>
        <event on="onPackageSetup" fire="\QUI\Bricks\Events::onPackageSetup"/>
    </events>
</quiqqer>

Keep listener methods focused. Return early when the listener does not apply to the current context.

Import Rules

When events.xml is imported:

• entries without on are ignored
• entries without fire are ignored
• priority is optional
• default priority is 10
• listeners are registered through the QUIQQER event manager

Real Package Shape

quiqqer/bricks registers listeners for site, template, setup, project, and output events:

<?xml version="1.0" encoding="UTF-8"?>
<quiqqer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://www.quiqqer.com/docs/schemas/2.x/events.xsd">
    <events>
        <event on="onSiteSave" fire="\QUI\Bricks\Events::onSiteSave"/>
        <event on="onSmartyInit" fire="\QUI\Bricks\Events::onSmartyInit"/>
        <event on="onPackageSetup" fire="\QUI\Bricks\Events::onPackageSetup"/>
        <event on="onDeleteProject" fire="\QUI\Bricks\Events::onDeleteProject"/>
        <event on="onOutputParseEnd" fire="\QUI\Bricks\Events::onOutputParseEnd"/>
    </events>
</quiqqer>

Practical Checklist

Before adding events.xml:

• Use existing event names from the framework or package you integrate with.
• Point fire to an autoloadable static method.
• Match the listener method parameters to the event.
• Keep listener code small and predictable.
• Log exceptions that need later inspection.
• Use priority only when listener order matters.