Admin Ui Laravel Package

Getting Started

ibexa/admin-ui is the bundle that renders the Ibexa DXP Back Office. It is not a package you bolt onto an existing Symfony admin — it ships as part of the Ibexa DXP metapackage, so the real first step is installing the distribution:

composer create-project ibexa/website-skeleton my-project
# or, inside an existing DXP install:
composer require ibexa/admin-ui

Then run the installer, compile assets, and log in at /admin:

php bin/console ibexa:install
php bin/console ibexa:graphql:generate-schema   # if you use GraphQL
yarn install && yarn encore prod
php bin/console cache:clear

Where to look first, in this order:

1. README.md — points straight at the canonical docs, https://doc.ibexa.co/en/latest/install/ and the "Extending Back Office" page (https://doc.ibexa.co/en/4.4/extending/extending_back_office/). Treat those as the real manual; the repo itself is code, not prose.
2. vendor/ibexa/admin-ui/ — bundle class, Resources/config/ (services, routes, menu items, field-type view mappings), Resources/views/ (Twig), Resources/public/ (compiled JS/CSS, plus js/ source modules).
3. docs/field-type-validator-usage.md — the one piece of first-party documentation in-repo, and the most common front-end extension task you will hit.
4. vendor/ibexa/admin-ui/CHANGELOG / release notes — the release notes are consistently maintained and are the fastest way to know whether a Back Office bug you are seeing was already fixed upstream.

The canonical first use case is: you have a custom Field Type and need it to be editable in the Back Office. That means registering admin view templates for the field type (edit/create and view variants), wiring a JS module for the editor widget, and optionally a validator extending ibexa.BaseFieldValidator. The second most common first task is overriding a Back Office Twig template to add a tab, column, or panel.

Implementation Patterns

Template overrides, not vendor edits. Ibexa resolves Back Office templates through the standard bundle/theme override mechanism. Put an override in templates/bundles/IbexaAdminUiBundle/... mirroring the vendor path, or declare a custom design/theme. Never patch vendor/ibexa/admin-ui/Resources/views — a composer update silently reverts it, and the file is excluded from your VCS review.

Field Type admin views. Register the edit/view templates against the field type identifier in your bundle's Resources/config/fieldtypes.yml (ezpublish.fieldType.<identifier>.extra / the ibexa equivalent), then build the template from the admin UI form components. Keep the view template dumb — pass data up via hidden inputs and let the PHP Field Type toHash()/fromHash() do the validation, so you do not duplicate rules in JS.

Client-side validation via BaseFieldValidator. The documented pattern is subclass, configure, init:

class Validator extends window.ibexa.BaseFieldValidator {
    validateInput(event) {
        const value = event.target.value.trim();
        return {
            isError: value.length < 3,
            errorMessage: 'Must be at least 3 characters',
        };
    }
}

const validator = new Validator({
    classInvalid: 'is-invalid',
    fieldSelector: '.ez-field-edit-ibexa-mytype',
    eventsMap: [{
        selector: '.ez-field-edit-ibexa-mytype input',
        eventName: 'blur',
        callback: 'validateInput',
        invalidStateSelectors: ['.ez-field-edit-ibexa-mytype'],
        errorNodeSelectors: ['.ez-field-edit-mytype'],
    }],
});
validator.init();

eventsMap is the whole model: one entry per input/event pair. For complex markup, override findValidationStateNodes, findErrorContainers, and findExistingErrorNodes rather than bending CSS selectors — they each receive (fieldNode, input, selectors) and return node arrays, which is far more robust for tables and repeated sub-forms.

Re-init on DOM mutation. Anything rendered after page load (sub-items lists, translation selects, dynamically added collection rows) needs validator.reinit(), which tears down and re-attaches listeners. The 5.0.x release notes show upstream hitting exactly this class of bug — "dropdown lazy initialization for dynamically populated translation selects" — so assume your widget will be re-rendered and plan the lifecycle hook.

Back-end extension. Custom admin screens normally mean: a Symfony controller (often extending the admin UI's REST/abstract controllers), a route added under the ibexa. prefix, a menu item declared in YAML so it appears in the left navigation, and a Twig template extending the admin pagelayout to inherit the chrome, breadcrumbs, and JS bootstrapping. Use dependency injection and compiler passes to decorate existing services rather than class_alias hacks; the bundle is large and its services are tagged (ibexa.admin_ui.*) for exactly this.

Config-driven extension points are the stable ones. Recent releases add named extension points rather than changing behaviour: "extensibility point to richtext config" (IBX-10827), "content edit translation selector extension point" (IBX-11492), and table action cells switching to a dropdown when there are more than N actions (IBX-11289). When you need to change Back Office behaviour, check the release notes for an extension point added for that purpose before monkey-patching JS.

Translations and multi-language. Back Office strings go through the standard Symfony translator with the ibexa_* domains; add your own translation files to your bundle rather than editing vendor ones. Anything user-facing that is language-dependent (date pickers, content names in trees) has historically broken under translation — the 4.6.29 notes fix the datepicker "always in English despite BO language change" — so test every custom widget with a non-English Back Office language and with a translated content item.

Gotchas and Tips

The licence is not what NOASSERTION suggests. It is dual: Ibexa Business Use License 2.4+ or GPLv2. In practice, production Back Office use requires a valid Ibexa DXP subscription; the GPLv2 branch is a copyleft option, not a permissive one. Get this cleared before you build a product on it — it affects whether you can redistribute and what obligations attach to your modifications.

Version alignment is strict. This bundle is a sibling of ibexa/core, ibexa/content-forms, etc. Mixing a 4.6 admin UI with 5.0 core will fail in confusing ways (missing services, Twig namespace errors). Pin the whole Ibexa family to the same minor. Note that 5.0.7 bumped symfony/* to 7.4 LTS — if you are on Symfony 6.x you are on the 4.6 line, and a naive composer update can drag you across a major version.

Assets are compiled, not read from source. Editing a file under Resources/public/js in your own bundle does nothing until yarn encore dev/prod runs and cache:clear executes. If your change "didn't apply", check the compiled asset hash and the browser cache before debugging logic. The bundle's own JS is built from Resources/public/js sources with a Node toolchain, so custom modules should follow the same import/namespace conventions (window.ibexa.*) rather than bundling a second, competing copy of a library.

init() is one-shot. Calling init() twice on the same field double-binds handlers and you get duplicate error messages. Use reinit() after DOM changes. Similarly, error nodes appended by the validator are not removed for you on success — verify your findExistingErrorNodes override actually matches the class the base validator inserts (ez-field-error), or errors accumulate with each blur.

Selectors break silently. Nothing throws if fieldSelector matches zero nodes; validation just never runs. When a field "isn't validating", log document.querySelectorAll(fieldSelector).length first — nine times out of ten the answer is the CSS class changed between Ibexa versions (the ez- prefix survives in many places, but do not assume it).

Escape everything you render into list/tree views. IBX-11775 in 4.6.30 is exactly this: "Fixed escaping content name in sub-items list". If you add a custom column or tree node label, escape content names — they are user-supplied and the admin UI is a privileged session, which makes XSS here considerably worse than on the front end.

Debugging a Back Office page: use the Symfony profiler for the request, bin/console debug:container | grep ibexa.admin_ui for services, bin/console debug:router | grep ibexa for routes, and bin/console debug:twig --filter=<name> to confirm template overrides resolve to your file. Twig's {% dump %} plus the profiler's template panel shows the winning template path, which settles override-priority arguments instantly.

Enterprise vs OSS divergence is real. The release notes tag Behat scenarios that "should not be run on OSS" (IBX-10737). Some admin UI features — commerce, product collections, corporate accounts, segments — are simply absent without the commercial edition. Do not design around a UI element you saw in a demo without confirming it lives in the OSS bundle; if the class or route is missing on your install, that is usually why, not a broken build.

Upgrade surface is large but well-documented. Release notes carry issue IDs (IBX-xxxxx) and PR links for every change, in both 4.6.x and 5.0.x, frequently merged across branches. Before reporting a Back Office rendering glitch, grep the release notes for the symptom — items like "Rendering glitch" (IBX-11440), "Fixed collapse header text clipping" (IBX-10479), and "Handle left position in popup menu" (IBX-11501) show these are known-moving parts, and a patch release likely already covers you.