User Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — it has no service provider, no config/user-bundle.php, and no Artisan commands. Before you invest time, confirm your stack is Symfony + Sonata Admin + Sonata UserBundle + Doctrine ORM. If you are on Laravel, stop here; the effort to port it outweighs rewriting the ~20 lines of "admin user + roles" it saves.

Assuming a Symfony app:

1. Install (expect to pin a version — the bundle is pre-1.0 and effectively unmaintained):

   composer require runroom-packages/user-bundle
   

2. Register the bundle in config/bundles.php:

   Runroom\Packages\UserBundle\RunroomUserBundle::class => ['all' => true],
   

3. Install Sonata's prerequisites first. The bundle assumes sonata-project/admin-bundle, sonata-project/user-bundle, sonata-project/doctrine-orm-admin-bundle, and symfony/security-bundle are already wired up. Do that before touching this bundle or you will chase mapping errors.
4. Create your own entity extending the bundle's mapped superclass. The bundle ships an AdminUser base class; you own the concrete entity in src/Entity/AdminUser.php (or equivalent) and point Doctrine at it.
5. Configure config/packages/runroom_user.yaml with your entity class, manager class, and table name.
6. Generate schema with bin/console make:migration && bin/console doctrine:migrations:migrate (or doctrine:schema:update --force in dev).
7. First use case: log into /admin with a user created via bin/console sonata:user:create or a fixture.

Where to look first:

• vendor/runroom-packages/user-bundle/src/Entity/ — the base class you'll extend
• vendor/runroom-packages/user-bundle/src/Manager/ — the user manager service
• vendor/runroom-packages/user-bundle/src/Admin/ — Sonata admin classes
• config/packages/security.yaml — your firewall must use the Sonata user provider
• config/packages/sonata_user.yaml — the class key must match your entity

Implementation Patterns

Extending the base entity. You almost never use the bundle's entity directly. Subclass it, add your fields, and register the subclass in both this bundle's config and sonata_user.yaml:

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Runroom\Packages\UserBundle\Entity\AdminUser as BaseAdminUser;

#[ORM\Entity(repositoryClass: AdminUserRepository::class)]
#[ORM\Table(name: 'admin_user')]
class AdminUser extends BaseAdminUser
{
    #[ORM\Column(type: 'string', length: 100, nullable: true)]
    private ?string $displayName = null;
}

Overriding the admin class. The bundle exposes a Sonata Admin service for users. Re-declare it in config/services.yaml with your own class (or extend the bundle's) to add/remove form fields, list columns, and filters. Register the service with the sonata.admin tag:

App\Admin\AdminUserAdmin:
    arguments:
        - ~
        - App\Entity\AdminUser
        - ~
    tags:
        - { name: sonata.admin, manager_type: orm, label: 'Admin users' }

Using the manager instead of the repository. Day-to-day user creation should go through the bundle's user manager (it handles password encoding and role normalization):

$manager->createWithPassword($user, $plainPassword);
$manager->save($user);
// or
$manager->findOneByEmail($email);

Adding roles. Use Sonata's role hierarchy in config/packages/security.yaml rather than hard-coding ROLE_ADMIN strings; the bundle reads roles from the user entity but does not manage the hierarchy.

Fixtures / seed data. Do not rely on the bundle for fixtures. Write a normal Doctrine fixture that calls the user manager — this is the pattern that survives composer updates.

Password reset. If the bundle wires a reset flow, verify it against your mailer config; otherwise use Sonata's built-in sonata:user:reset-password command.

Integration tip: keep the firewall explicit. Point the Sonata admin firewall at your AdminUser entity's provider, and load the provider from the entity's email field. Do not reuse a users provider used for front-end customers.

Gotchas and Tips

• It is not a Laravel package. No php artisan, no .env conventions, no facades. If the evaluation is "should we pull this into a Laravel app?" — no. It requires Symfony Kernel, DependencyInjection, and Sonata.
• Unmaintained / pre-1.0. Zero dependents and a low opportunity score are red flags. Pin an exact version in composer.json and be prepared to vendor a fork if it breaks against a new Sonata release.
• Version alignment is the #1 failure mode. Sonata Admin 3 vs 4, Sonata User 5 vs 6, and Doctrine ORM 2 vs 3 all have incompatible APIs. Check the bundle's composer.json constraints against your lockfile before installing.
• Doctrine inheritance surprises. The base entity is a mapped superclass. Two common errors: (a) forgetting to set #[ORM\MappedSuperclass] on your abstract intermediate class, and (b) two entities mapping to the same table name. Set the table in your subclass only.
• Schema diffs will try to drop the bundle's base columns if your subclass is missing attributes. Run bin/console doctrine:schema:validate after every entity change, not just schema:update.
• Cache is your debugger. After changing entity class names in config, run bin/console cache:clear — otherwise the container serves stale class references and you get "entity not mapped" exceptions.
• Inspect services with:

  bin/console debug:container | grep -i user
  bin/console debug:config runroom_user
  bin/console debug:router | grep -i sonata
  

• Firewall ordering matters. The admin firewall must come before the main firewall in security.yaml, and must use form_login with the Sonata admin login check path, or you get redirect loops.
• Password hasher config drift. If the bundle hashes with one encoder and your security.yaml verifies with another, login silently fails. Both must reference the same App\Entity\AdminUser.
• Extension points are limited to what's under src/Entity, src/Manager, and src/Admin. Anything beyond subclassing and re-tagging services is a fork. Prefer extending and overriding over editing vendor code.
• Test coverage in your app is on you. Write a smoke test that loads /admin/login and a functional test that authenticates; the bundle ships almost no tests, so regressions after a Sonata bump will surface in your app first.