User Bundle Laravel Package

Getting Started

Stack check before anything else. grizzlylab/user-bundle is a fork of FOSUserBundle — a Symfony bundle. It registers via config/bundles.php, hooks Symfony's security firewall, and ships Doctrine ORM/ODM mappings. There is no service provider, facade, artisan command, or guard that Laravel's container will see. Composer will install it (type: symfony-bundle), but php artisan will never load it. A Laravel developer's honest starting point is: this is not a package you can use day-to-day in Laravel. Treat it as reference reading and pick the real path:

• New Laravel app → laravel/breeze (starter), laravel/fortify (headless), or laravel/jetstream (teams/2FA). These give you guards, hashing, verification, reset, and 2FA as first-party code.
• Inherited Symfony app already on FOSUserBundle → the steps below apply.

Read the fork diff first, not the docs. 0 stars / 0 dependents means unaudited code. Forks of FOSUserBundle almost always exist for one reason: relaxing a PHP/Symfony constraint so it installs on a newer runtime. Confirm that is all it changes, then trust it for nothing more:

composer show grizzlylab/user-bundle
git diff friendsofsymfony/user-bundle:<tag>..HEAD -- src/ Resources/config/ composer.json

Pin to an explicit commit — never dev-main on a security-path dependency:

"grizzlylab/user-bundle": "dev-main#<sha>"

Minimal Symfony wiring (if you actually have Symfony):

1. Register FOS\UserBundle\FOSUserBundle in config/bundles.php.
2. Add config/packages/fos_user.yaml (db_driver, firewall_name, user_class, from_email).
3. Create App\Entity\User extending FOS\UserBundle\Model\User, mapped to a table.
4. Import routes: fos_user: { resource: "@FOSUserBundle/Resources/config/routing/all.xml" }.

First use case: get /register and /login rendering, then exercise register → confirm email → login → logout → password reset end-to-end. That loop is where FOSUserBundle breaks first on modern Symfony (mailer contract, token entity, hash encoder).

Implementation Patterns

The firewall is the integration surface. Everything routes through security.yaml; the bundle supplies the provider and the User model, the rest is your config:

security:
  password_hashers:            # `encoders:` on <5.3
    FOS\UserBundle\Model\UserInterface: auto
  firewalls:
    main:
      form_login:
        provider: fos_userbundle
        csrf_token_id: authenticate
      logout: true
  providers:
    fos_userbundle:
      id: fos_user.user_provider.username_email

Use events, not controller overrides. The classic FOSUserBundle trap is overriding controllers/templates under src/Resources/FOSUserBundle/.... That copy is fragile and silently stale after upgrades. Instead subscribe to lifecycle events and do your work there:

public static function getSubscribedEvents(): array
{
    return [
        FOSUserEvents::REGISTRATION_INITIALIZE => 'onInitialize',
        FOSUserEvents::REGISTRATION_CONFIRMED  => 'onConfirmed',   // assign roles, tenant, welcome mail
        FOSUserEvents::RESETTING_RESET_SUCCESS => 'onPasswordReset',
    ];
}

REGISTRATION_CONFIRMED is the right hook for default roles, tenant binding, or welcome emails — do it there, not in a copied RegistrationController.

Configure behavior, don't code it. fos_user.registration.confirmation.enabled, fos_user.resetting.token_ttl, fos_user.service.user_manager, and fos_user.from_email cover most "customize the flow" asks. Reach for service.user_manager only when config can't express the rule.

Laravel-equivalent patterns (what you will actually build):

• Registration/login → Breeze scaffolds controllers, requests, and Blade views you own and edit freely.
• Password reset / email verification → enabled via Fortify::features([...]) or Breeze defaults; mailer integration is the Mail:: facade with ResetPassword and VerifyEmail notifications.
• Custom user fields → migrate the users table or add a profiles table; no base class to extend.
• Roles / groups → Laravel's HasRoles + policies/gates; groups map naturally to teams (Jetstream) or a teams table you own.
• Social / OAuth → laravel/socialite (well maintained) rather than any fork.

Gotchas and Tips

The decisive gotcha: stack mismatch. A Laravel service provider cannot load a Symfony Bundle class. You can composer require it, but nothing in the request lifecycle will invoke it. If a task says "add user management with this package" on a Laravel app, the correct action is to close the ticket and use Breeze/Fortify — not to attempt an adapter.

Deprecation is inherited, not solved. Upstream FOSUserBundle is deprecated by the Symfony community; this fork moves the liability, it does not remove it. Any CVE in the auth path is yours to triage because 0 dependents means no downstream pressure and 0 stars means no contributor pool. Budget a named maintainer before you adopt, or don't adopt.

Version pins bite first. These forks typically pin PHP 7.x / Symfony 3–4. Check composer.json require before writing any code — a hard blocker discovered after wiring wastes a day. On modern Symfony (6/7), expect install or runtime failures on password_hashers, mailer contracts, and the token entity.

Silent runtime breakage on upgrade. Auth contracts (UserInterface, UserProviderInterface, hasher factories) change between Symfony minors. The bundle fails at runtime, not compile time, so add an integration test for the full register→reset loop to your CI before you trust an upgrade.

Fork divergence tax. Every Stack Overflow answer for FOSUserBundle assumes upstream. When the fork behaves differently, you debug by reading source — there is no doc trail. Keep your diff against upstream pinned in a comment so future-you knows what changed.

Password hash lock-in. The longer credentials sit in the bundle's stored hash format, the harder migration gets. If you are only using it as a stopgap, migrate users incrementally (rehash-on-login) and set a deprecation date on day one.

Debugging path. Start at security.yaml (provider and firewall names must match fos_user.yaml firewall_name), then bin/console debug:container | grep fos_user, then the event dispatcher (debug:event-dispatcher FOSUserEvents). 90% of "login doesn't work" reports trace to a provider/firewall name mismatch, not the bundle.

Extension points to prefer: fos_user.service.user_manager override, event subscribers, and config keys. Extension points to avoid: controller/template overrides under Resources/ — they are the most cited source of upgrade pain in FOSUserBundle history.