User Bundle Laravel Package

Getting Started

This package is a fork of sonata-project/user-bundle published under rmzamora/user-bundle. It is archived and has no dependents, so treat it as a pinned, vendored snapshot of SonataUserBundle rather than a maintained dependency. Before you build on it, diff the fork against the upstream sonata-project/user-bundle release it was forked from — the day-to-day API you'll use is SonataUserBundle's, and that upstream is where docs and examples live.

Minimal install:

# Because it is not a normal maintained package, pull it via VCS
composer config repositories.sonata-user-fork vcs https://github.com/rmzamora/SonataUserBundle
composer require rmzamora/user-bundle:"<branch-or-tag>"

The fork expects the usual Sonata stack — confirm each is present in composer.json, since the fork's own constraints may be stale:

composer require sonata-project/admin-bundle sonata-project/doctrine-orm-admin-bundle \
                 friendsofsymfony/user-bundle

Enable in config/bundles.php (order matters — user bundle after admin/FOS):

FOS\UserBundle\FOSUserBundle::class            => ['all' => true],
Sonata\AdminBundle\SonataAdminBundle::class    => ['all' => true],
Sonata\DoctrineORMAdminBundle\SonataDoctrineORMAdminBundle::class => ['all' => true],
Sonata\UserBundle\SonataUserBundle::class      => ['all' => true],

Look first at: the fork's Resources/config/ (services and admin definitions), Entity/BaseUser.php / Entity/BaseGroup.php (the classes you extend), and DependencyInjection/Configuration.php (the sonata_user: tree). Those three tell you exactly what the fork changed and what it expects.

First use case: create your App\Entity\User extending the bundle's base user, point fos_user and sonata_user at your classes, run migrations, then create an admin:

// src/Entity/User.php
namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Sonata\UserBundle\Entity\BaseUser;

#[ORM\Entity]
#[ORM\Table(name: 'app_user')]
class User extends BaseUser
{
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    protected $id;
}

# config/packages/fos_user.yaml
fos_user:
    db_driver: orm
    firewall_name: main
    user_class: App\Entity\User
    group:
        group_class: App\Entity\Group

# config/packages/sonata_user.yaml
sonata_user:
    security_acl: false
    manager_type: orm
    class:
        user: App\Entity\User
        group: App\Entity\Group

Then bin/console doctrine:schema:update --force (or generate a migration) and bin/console fos:user:create admin --super-admin. Log into /admin and confirm the Users and Groups sections appear.

Implementation Patterns

Admin registration. The bundle ships sonata.user.admin.user and sonata.user.admin.group services. Most apps just reference them in sonata_admin.yaml:

sonata_admin:
    security:
        handler: sonata.admin.security.handler.role
    dashboard:
        blocks:
            - { type: sonata.admin.block.admin_list, position: left }

If you need custom columns/filters, create an Admin subclass extending the bundle's admin class and override the service definition rather than editing vendor code.

Roles and hierarchy. SonataUserBundle's big value over raw FOSUserBundle is first-class role management. Define a base hierarchy and let admins assign from it:

security:
    role_hierarchy:
        ROLE_ADMIN:       [ROLE_USER, ROLE_SONATA_ADMIN]
        ROLE_SUPER_ADMIN: [ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH]

Keep ROLE_SUPER_ADMIN out of the editable role list unless you explicitly want admins minting super-admins.

Profile / registration frontend. The bundle reuses FOSUserBundle's controllers and routes. Import them once and override templates in templates/bundles/FOSUserBundle/ (or the Sonata equivalents) instead of copying controllers:

# config/routes.yaml
fos_user:
    resource: "@FOSUserBundle/Resources/config/routing/all.xml"

Impersonation. Grant ROLE_ALLOWED_TO_SWITCH and expose the switch link from the admin user list. This is the feature devs use daily for reproducing user-specific bugs. Test it in a non-prod environment only.

Dashboard blocks. For a user-facing profile block, register a custom BlockService and tag it sonata.block. The bundle's own blocks (sonata.user.block.* in older versions) are a good template.

Programmatic user creation. In services/commands, inject fos_user.user_manager rather than the entity manager — it handles password hashing and canonical fields correctly:

$user = $this->userManager->createUser();
$user->setUsername($name)->setEmail($email)->setPlainPassword($pw)->setEnabled(true);
$this->userManager->updateUser($user);

Gotchas and Tips

• Archived + zero stars. Do not expect fixes. Pin an exact tag in composer.json, commit composer.lock, and keep a diff against the equivalent upstream sonata-project/user-bundle tag. If the fork adds nothing you need, drop it and use upstream — you'll get security patches.
• Composer name ambiguity. The repo is SonataUserBundle but the package is rmzamora/user-bundle. Composer resolves by composer.json name, not the repo name; if the fork's name differs from what you require, the VCS install will fail with "could not be found." Verify composer show rmzamora/user-bundle after install.
• Class inheritance mapping. Extending BaseUser requires @ORM\Entity on your subclass and correct @ORM\Table; forgetting it gives silent "no mapped entity" errors. If you use resolve_target_entities, run doctrine:schema:validate before migrating.
• Firewall ordering. fos_user firewall and the sonata_admin security context must not overlap patterns. A common bug is the admin area being caught by the main firewall, producing redirect loops or 403s after login. Put access_control entries for ^/admin before ^/.
• Locking yourself out. Editing your own admin user and removing ROLE_ADMIN/ROLE_SUPER_ADMIN immediately locks the UI. Keep a break-glass CLI path (fos:user:promote) or seed a super-admin via a fixture.
• Stale admin cache. Sonata caches admin metadata aggressively. After config or entity changes, bin/console cache:clear and, if using the admin cache, clear the sonata_admin cache pool. Symptom: new fields not appearing or "service not found" for admin classes.
• Password hashing. Never set password directly on the entity — always setPlainPassword() followed by a manager update, or the hasher won't run and login will fail silently.
• Deprecation noise. The fork likely targets an older Symfony/PHP range. Expect @required-style DI deprecations and possibly incompatibilities with Symfony 5.4+/6. Audit the fork's composer.json require block against your Symfony version before wiring it in.
• Translation and template overrides belong in templates/bundles/ and translations/, not in vendor. This is the safest place to modernize the fork's Bootstrap 3-era markup without touching the archived source.
• Extension points you can rely on: service overrides in services.yaml (sonata.user.admin.user), custom Admin subclasses, a custom RolesBuilder, and replacing the user manager. All of these let you extend behavior without forking the fork.