Hooks, Slots & Registry

This page is the contract between core and plugins. Every entry below exists in Xilancer 4.3.0. Payloads are scalars and arrays; models, requests, passwords, OTPs, and tokens are never passed.

Conventions

• Actions are noun.verb in the past tense: order.paid, job.created.
• Filters are noun.data or domain.name: user.create_data, checkout.price.calculate.
• Slots are area.element: order.details_after.
• Registry domains are plural-ish nouns: gateway, admin.menu.
• Priorities are integers. Lower runs first. Default is 10. Ties are FIFO.
• Actions fire after the database write.
• Data filters run before create or update, and the allow-list is re-asserted after.

Registering

// Filter
$this->ctx->hooks->addFilter('checkout.price.calculate', $callback, 10);

// Action
$this->ctx->hooks->addAction('order.paid', $callback, 10);

// Slot
$this->ctx->slots->register('order.details_after', 'my-plugin.panel', $renderer, 10);

// Registry
$this->ctx->registry->register('admin.menu', 'my-plugin', $entry, 10);

// Remove
$this->ctx->hooks->removeFilter('checkout.price.calculate', $callback);
$this->ctx->hooks->removeAction('order.paid', $callback);
$this->ctx->slots->remove('order.details_after', 'my-plugin.panel');
$this->ctx->registry->remove('admin.menu', 'my-plugin');

remove* compares closures by object identity, strings by value, and [object, method] pairs by object and method name. Register the same callable you want to remove.

Filters

A filter receives a value and optional context, and must return the same type. If no plugin handles the hook, plugin_apply_filters() returns the input unchanged.

Core filters

Filter rules

1. Always return the same type you received.
2. Never mutate the input by reference; return a new value.
3. Do not assume the context keys exist. Use ?? defaults.
4. Do not throw. A throw is caught and the original value is used, which hides your change.
5. Do not perform writes in a filter. Use an action for side effects.

Actions

Actions receive (id, payload). The payload is an array. It always includes the IDs needed to re-query, never a model.

Users and auth

Jobs, projects, proposals, offers

Orders and checkout

Wallet, subscription, commission

Other actions

Action rules

1. Actions fire after the write and outside transactions.
2. An action that throws is caught by plugin_do_action() and reported. Other listeners still run.
3. Do not assume ordering between unrelated actions.
4. Payloads are snapshots. Re-query if you need current state.
5. Keep actions fast. Queue heavy work.

Slots

Slots render HTML. Each renderer receives a context array and returns a string. A throwing renderer is skipped per renderer; the rest of the slot still renders.

Slot rules

1. Escape every value with htmlspecialchars($value, ENT_QUOTES, 'UTF-8').
2. Do not assume ambient Blade variables. Use the context array.
3. Do not render a <form> inside another form. Checkout coupon fields are the exception because the slot is placed inside the form on purpose.
4. Keep output small. A slot renders on every page view that reaches it.
5. Return an empty string, not null, when there is nothing to show.

Registry domains

Registry entries are structured data, not HTML. plugin_registry($domain) returns entries keyed by ID, priority ordered.

Gateway example

$this->ctx->registry->register('gateway', 'mygateway', [
    'id' => 'mygateway',
    'label' => 'My Gateway',
    'module' => 'MyGateway',
    'ipn_route' => 'mygateway.ipn',
    'settings_prefix' => 'mygateway',
    'enabled_option' => 'mygateway_enabled',
]);

Core's PaymentGatewayList, IPN routing, and settings screen consume this. The plugin still needs a payment.charge filter to start a checkout and a payment.complete call to settle it.

Dashboard menu example

$this->ctx->registry->register('dashboard.menu', 'my-plugin', [
    'label' => 'My Reports',
    'route' => 'my-plugin.reports',
    'icon' => 'fa-solid fa-chart-line',
    'roles' => ['freelancer', 'client'],
]);

Cloud storage driver example

$this->ctx->registry->register('cloud_storage.driver', 'my-driver', [
    'id' => 'my-driver',
    'label' => 'My Storage',
    'disk' => 'my-driver',
    'prefix' => 'mydriver',
    'cloud' => true,
    'fields' => [
        'key' => ['label' => 'Access key', 'required' => true],
        'secret' => ['label' => 'Secret', 'required' => true, 'secret' => true],
        'region' => ['label' => 'Region', 'required' => true],
    ],
]);

Plugin-provided hooks

These are fired by plugins, not core. Core may listen to some of them.

Helpers

Core uses these. Plugins may call the read-only ones, but registering through PluginContext is preferred.

Dispatch semantics

Filter dispatch

$value = plugin_apply_filters('checkout.price.calculate', 100.0, $context);

• No listeners: returns 100.0.
• Framework absent: returns 100.0.
• Callback throws: caught, report() called, returns the value from before that callback.
• Callbacks run in priority order.

Action dispatch

plugin_do_action('order.paid', $orderId, $meta);

• No listeners: no-op.
• Callback throws: caught, report() called, remaining callbacks still run.
• Actions cannot change a value. Use a filter for that.

Slot dispatch

echo plugin_render_slot('order.details_after', ['order_id' => $id, 'role' => 'client']);

• No renderers: returns an empty string.
• One renderer throws: it is skipped, others render, error recorded.
• Output is concatenated in priority order.

Paginator

$paginator = plugin_filter_paginator($paginator, 'search.jobs.results', ['filters' => $filters]);

• Requires an object with getCollection() and setCollection().
• A non-array return is ignored.
• The same paginator instance is returned.

What core deliberately does not hook

Adding a core seam

Plugin authors cannot add seams. If you need one, open a request with:

1. The hook name and type (filter, action, slot, registry).
2. The exact payload and types.
3. The file and line where it should fire.
4. Why an existing seam cannot do the job.
5. Whether it should be gated by plugin_has_filter().

Core-side checklist:

1. Guard with function_exists('plugin_do_action').
2. Gate expensive payloads with plugin_has_filter('<hook>').
3. Actions after writes, outside transactions.
4. Data filters before create/update, with an allow-list.
5. Slots outside forms, tab groups, and JS-moved modals.
6. Add the row to plugins/HOOKS.md with file and line.

Last updated: October 21, 2026