Admin Ui Assets Laravel Package

Getting Started

This is not a PHP library you integrate directly — it is the front-end asset bundle (SCSS, JS, images, fonts) consumed by ibexa/admin-ui to render the Ibexa DXP Back Office. Treat it as a vendor asset package, not an API.

1. Install Ibexa DXP first. The package is pulled in transitively by the admin UI; you normally should not composer require it on its own. Confirm it exists under vendor/ibexa/admin-ui-assets after a standard DXP install.
2. Look at package.json and the asset entry points first. That tells you what is compiled, which bundler is expected, and what the public asset paths are. Then inspect the SCSS/JS source directories to find the component you need to override.
3. Install/refresh assets in your project:

   php bin/console assets:install --symlink
   php bin/console cache:clear
   

   In production use a real copy rather than symlinks, and run your normal Encore/Webpack build.
4. First real use case: override a Back Office style or JS behaviour from your own project rather than editing vendor files. Add your override to your project’s Encore entry, import the vendor asset as a base, and rebuild. For template-level changes, override the relevant admin template in your project’s admin theme.

If you are only doing backend/PHP work, you will rarely touch this package directly. Its day-to-day value is for developers theming or extending the Back Office.

Implementation Patterns

Never edit vendor/. Composer updates will overwrite your changes. Keep all customisations in your project bundle or admin theme.

SCSS extension pattern. Import the vendor stylesheet as a base, then override variables/components in your own entry:

// assets/scss/admin.scss
@import "~@ibexa/admin-ui-assets/..."; // use the actual entry path from package.json
// project overrides below

Configure your Encore/Sass loader with the vendor path in includePaths so imports resolve cleanly. Prefer overriding CSS custom properties and SCSS variables over copying whole files.

JS extension pattern. Import the package module you need and wrap/decorate its exported behaviour from your own admin entry. Register your entry through the same Encore configuration used by the admin UI so it loads after the vendor bundle. Avoid monkey-patching global objects where a module import is available.

Template override pattern. Back Office templates are overridden through the standard Ibexa design/theme mechanism, not by changing this package. Place the override in your project’s admin theme at the same relative template path and clear the cache. This is the correct integration point for markup changes that require new CSS/JS hooks.

Version alignment pattern. Match the package branch/tag to your Ibexa DXP version. The README explicitly notes that the 4.x branch is used for eZ Platform 2.5.x LTS — a reminder that branch names do not track DXP major versions naively. Pin through composer.lock and upgrade it together with the rest of Ibexa.

Maintainer/release workflow. Only if you are contributing to the package itself:

npm install
npm run prepare-release
sh bin/prepare_release.sh -v 1.0.0 -b master

Do not run prepare-release or the release script in application deployments; those are packaging steps that regenerate distributable assets.

CI/deployment pattern. In CI, install Composer dependencies, run assets:install with the production flags, run your Encore production build, then clear/warm cache. Commit your project-level asset sources and lockfile, never node_modules or generated vendor assets.

Gotchas and Tips

• License is not permissive-by-default. The package is dual-licensed under the Ibexa Business Use License and GPLv2 (NOASSERTION on the registry). Do not assume MIT-style reuse. Get legal review before extracting assets into a non-Ibexa project.
• There is no PHP extension point here. No services, no events, no DI configuration. If you need backend behaviour, you are in the wrong package — look at ibexa/admin-ui or core.
• Low stars/dependents is expected, not a red flag. This is an internal DXP dependency. Support comes through an Ibexa subscription and the official docs, not GitHub issues.
• Stale assets after changes. If styles or JS do not update, check in order: Encore build actually ran, assets:install copied/symlinked the new files, var/cache cleared, browser cache/hard reload. In dev, --symlink avoids stale copies.
• Path confusion between source and public assets. Debug against the compiled file served from public/bundles/..., then map back to the source entry. Source maps are your friend; enable them in dev only.
• Branch/version mismatches produce subtle breakage. Mixing a newer asset package with an older admin UI can leave missing components or broken selectors. Keep the whole Ibexa dependency set on compatible versions.
• Do not rely on internal class names or DOM structure. These are implementation details that change between releases. Hook onto documented markup, stable data attributes, or your own added classes via template overrides.
• Upgrades overwrite overrides placed incorrectly. If a customisation “disappears” after composer update, it was almost certainly made inside vendor/. Move it into the project theme/bundle.
• Useful extension points: SCSS variables and CSS custom properties, Encore entry configuration, admin theme template overrides, and standard Symfony asset installation. There is little else by design.