User Admin Bundle Laravel Package

Getting Started

Read this first: nucleos/user-admin-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no config publish, no Blade views, and no Illuminate dependency. It ships Sonata Admin classes that wrap NucleosUserBundle (and optionally NucleosGroupBundle) entities. If your day job is a Laravel monolith, the realistic use case is (a) you also run a Symfony back-office service, or (b) you're stealing the design as a feature checklist for Filament/Nova. Everything below assumes (a).

Minimum viable setup inside a Symfony app:

composer require nucleos/user-admin-bundle nucleos/user-bundle sonata-project/admin-bundle

1. Enable Nucleos\UserBundle\NucleosUserBundle, Sonata\AdminBundle\SonataAdminBundle, and Nucleos\UserAdminBundle\NucleosUserAdminBundle in config/bundles.php.
2. Import Sonata's routing (_sonata_admin + the admin route loader) — without this the pages 404 even though the service exists.
3. Configure the bundle (keys live in src/DependencyInjection/Configuration.php; typically you point at your user and group admin classes and the entity classes).
4. Run the migrations for the UserBundle tables — this bundle adds no schema of its own.

Where to look first, in order:

• src/Admin/UserAdmin.php and src/Admin/GroupAdmin.php — the whole package is essentially these two plus forms.
• src/Form/Type/ — UserFormType, GroupFormType, SecurityRolesType, UserRolesType. This is where role checkboxes and password handling are wired.
• Resources/config/*.xml — service definitions and the sonata.admin tags.
• tests/ — small enough to read end-to-end in under an hour, and better documentation than the README.

Platform note (3.11.0): the current release adds Symfony 8 support alongside the existing Symfony 6.4/7 range. That is the only change in the release — no new features, no deprecations, no signature changes. Practically it means you can adopt this on a Symfony 8 app, provided your Sonata AdminBundle version also supports Symfony 8 (check your lockfile; the bundle's constraint moving does not move Sonata's). If you're on Symfony 6.4/7, 3.11.0 is a no-op upgrade and safe.

First use case: a /admin back-office listing users with filters for enabled/locked/roles, an edit form with group assignment and role checkboxes, and a "reset password" field — gated behind ROLE_ADMIN (ideally ROLE_SUPER_ADMIN).

Implementation Patterns

Register the admins as tagged services. The tag is the whole game:

services:
    app.admin.user:
        class: App\Admin\UserAdmin
        arguments: [~, App\Entity\User, ~]
        tags:
            - { name: sonata.admin, manager_type: orm, group: Security, label: Users, admin_code: app.admin.user }

Miss manager_type or admin_code and the admin silently never appears in the sidebar — no error.

Subclass instead of configuring. There's little surface config here; the sanctioned extension point is class App\Admin\UserAdmin extends Nucleos\UserAdminBundle\Admin\UserAdmin and overriding configureFormFields(), configureListFields(), configureDatagridFilters(), configureRoutes(). Use $formMapper->with('Profile')->add('firstName')... and $listMapper->addIdentifier('username'). If the bundle exposes an admin_class config key, swap it there so the base service wiring stays intact.

Add app fields via the extension bundle. The base admin only knows the fields on NucleosUserBundle's User (username, email, roles, groups, enabled, locked, lastLogin, createdAt, confirmationToken). For firstName/lastName/phone, install nucleos/user-admin-extension-bundle or write a Sonata AdminExtension (sonata.admin.extension tag) — don't fork the admin just to add two fields.

Roles come from your firewall config. SecurityRolesType builds its checkbox list from security.role_hierarchy. An empty hierarchy means only ROLE_USER shows up. ROLE_SUPER_ADMIN won't render unless you declare it. This is the #1 "why is my role missing" support ticket.

Password handling is deliberately indirect. The admin's password field maps to plainPassword and runs through the user manager's updater. If you override the form and bind password directly, you'll write a plaintext (or double-hashed) value into the DB. Keep the "change password" checkbox pattern: only update when the field is non-empty.

Tenant scoping. Override createQuery() on your admin subclass, or register a Doctrine filter, so non-super-admins only see users from their tenant. Without this, sonata.admin.user is a cross-tenant enumeration endpoint — a real security bug, not a cosmetic one.

Impersonation. Add a custom Action/route that calls Symfony's switch_user firewall (?_switch_user=) and expose it as a per-row list action. Pair it with an audit log subscriber on sonata.admin.event.* or Doctrine onFlush so role grants and logins-as are traceable.

If you're mirroring this in Laravel (the more likely scenario): the bundle's feature set maps cleanly to a Filament UserResource + GroupResource with a roles checkbox list driven by a config array, Password::make()->dehydrated(fn ($state) => filled($state)), and a locked_at timestamp instead of a locked boolean. Treat the bundle's form types as your spec.

Gotchas and Tips

• It will not install into a Laravel app. There's no Laravel bridge; composer require may resolve, but the Bundle class and Symfony DI XML are inert. Failure mode is a class-not-found at boot, not a clean install-time rejection — so don't let a teammate "just try it." (Symfony 8 support in 3.11.0 changes nothing here.)
• Pin to the Sonata major you actually run. These admin classes implement AdminInterface and override its method signatures; a Sonata 4↔5 jump is a breaking change here. 3.11.0 only widens the Symfony constraint — it does not imply Sonata compatibility beyond what was already supported. Read the composer.json constraints rather than trusting dev-main, and pin a commit.
• Release cadence is dependency-driven. 3.11.0 is one PR, one contributor, zero issues, filed under "dependency." Expect most future releases to be constraint bumps and PHP/Symfony version support rather than features — plan for the package's behaviour to be stable and its platform support to be the thing that moves. Stars/dependents remain low.
• Services are private. $container->get('sonata.admin.user') throws in modern Symfony. Inject the admin by its code via AdminPool, or inject the specific service.
• Clear the cache after admin config changes. The sonata.admin.pool caches the dashboard/menu; a stale pool looks exactly like a broken tag. Also clear after a composer update that crosses a Symfony minor, since container compilation is where platform mismatches surface.
• groups requires NucleosGroupBundle. Install and configure it, or the group field and GroupAdmin will fail to resolve its entity. This is the second-most-common setup error.
• Never edit vendor/. Extension points, in order of preference: subclass the admin → AdminExtension tag → decorator on the bundle's services → NucleosUserAdminExtensionBundle. Only the last one is designed for "add a field to every user form."
• Debugging toolkit: bin/console debug:container --tag=sonata.admin, bin/console debug:router | grep admin, bin/console debug:config nucleos_user_admin. Those three answer 90% of "the page is blank / 404 / the admin is missing from the menu."
• Expect thin docs. At five stars and zero dependents this is effectively an internal tool that happens to be MIT-licensed. Budget time to read src/ rather than waiting on issues; the upside is that it's a dozen classes and genuinely legible.
• Localization: labels and messages are shipped in the Nucleos admin namespace. If you ship in more than English, override translation keys in translations/ rather than editing templates.
• Honest cost/benefit for a Laravel shop: if the only requirement is "admin users and groups," Filament, Nova, or Backpack gets you there in a day with far better docs and community. Adopt this bundle only if you already operate Symfony + Sonata and want the user/group admin for free.