Fos User Bundle Laravel Package

Getting Started

Read this first: this is not a Laravel package. nmalo/fos-user-bundle is a fork of the Symfony FOSUserBundle, published under a type: symfony-bundle Composer package. It ships no Laravel service provider, no facade, no config publishing, and no Illuminate dependency. composer require nmalo/fos-user-bundle inside a Laravel app will either fail on Symfony framework constraints or install a tree of Symfony components you never use. There is no php artisan entry point and nothing to register in config/app.php.

What to check before anything else

1. Is the fork still needed? Upstream FOSUserBundle has been in maintenance-only mode for years, and most of its functionality is now handled by symfony/security-bundle guards/authenticators plus make:user/make:auth. Diff the fork against upstream before assuming it contains anything you want:

   git clone https://github.com/nmalo/FOSUserBundle
   cd FOSUserBundle && git log --oneline --not origin/master
   composer show --all nmalo/fos-user-bundle   # inspect requires/conflicts
   

2. Check composer.json constraints. Look at require.symfony/* and require.php. A fork with 0 stars and 0 dependents almost certainly pins old Symfony majors, which means old PHP and, more importantly, no security backports.
3. Check the branch/version graph. If it tracks 2.x or an EOL 4.x/5.x line, the auth code is years behind current advisories.

First use case (the only one that makes sense): you are maintaining a legacy Symfony application that already depends on a FOSUserBundle fork and you need to understand or patch it. For that, Resources/config/ (service definitions), Model/User.php and Model/UserManager.php (the actual domain logic), and Security/ (login/logout handling) are where to look first.

If you are building new Laravel auth, the equivalents to reach for are laravel/breeze, laravel/jetstream, or laravel/fortify for session/UI auth, and laravel/sanctum or laravel/passport for token/API auth. There is no reason to pull a Symfony bundle into a Laravel app for this.

Implementation Patterns

If you are actually inside Symfony (legacy maintenance)

These are the patterns the bundle expects, and the ones you will have to learn to keep it running:

• Bundle registration. config/bundles.php returns [FOSUserBundle::class => ['all' => true]]. Note the fork's namespace may differ from upstream FOS\UserBundle — verify with the autoload.psr-4 block before writing use statements.
• User entity inheritance. Your App\Entity\User extends FOS\UserBundle\Model\User (or the fork's Model\User) and adds Doctrine ORM mapping on top, typically via XML/YAML in Resources/config/doctrine/ or attributes. You inherit username, email, password, roles, enabled, locked, lastLogin.
• Route import. config/routes/fos_user.yaml with resource: '@FOSUserBundle/Resources/config/routing/all.xml' — or import individual route files (security.xml, registration.xml, resetting.xml, profile.xml, change_password.xml) to expose only what you need.
• Configuration. config/packages/fos_user.yaml with db_driver: orm, firewall_name: main, user_class: App\Entity\User, and from_email. The service: sub-keys let you swap mailer, user_manager, util.password_encoder for your own implementations.
• Event hooks instead of overrides. This is the cleanest extension point and the one to prefer. Subscribe to FOSUserEvents::REGISTRATION_CONFIRM, REGISTRATION_COMPLETED, RESETTING_RESET_COMPLETED, CHANGE_PASSWORD_COMPLETED, SECURITY_IMPLICIT_LOGIN and react there rather than subclassing controllers.
• Overriding controllers/templates. Bundle inheritance (getParent() on a bundle class) or the templates/fos_user config keys. Both are brittle across fork updates — prefer events and a custom UserManager decorator.
• Custom UserManager. Decorate or replace the service to add your own lookup rules (e.g. case-insensitive email find) without forking the class:

  services:
    App\Security\UserManager:
      decorates: fos_user.user_manager
      arguments: ['@App\Security\UserManager.inner']
  

If you need Laravel and Symfony to coexist

Do not try to install this bundle in Laravel. If both apps must serve the same users, make one of them the identity authority and the other a client:

• Laravel as IdP. Expose laravel/passport (OAuth2) or a Sanctum-guarded JSON endpoint, and have Symfony use knpuniversity/oauth2-client-bundle or league/oauth2-client as the relying party. This keeps the legacy FOSUser tables read-only on the Symfony side.
• Shared database, separate managers. Both applications can read the same fos_user table, but never let both write passwords. Password hash interop is only plausible if both use bcrypt/argon2id with matching cost parameters — verify by round-tripping a hash through Hash::check() and Symfony's PasswordEncoderInterface before trusting it.
• Session/CSRF boundaries. Laravel's EncryptCookies/session driver and Symfony's session handler are not interchangeable; shared cookies across two frameworks is a debugging sinkhole. Prefer token-in-header auth for the cross-framework hop.

Gotchas and Tips

• Zero dependents is the headline risk. 0 stars and 0 dependents means no downstream users to find the bugs, no one filing security issues, and no one to merge your PR. Auth is the last place to accept unreviewed code. Treat any usage as a private fork you now own.
• Fork drift is silent. Because the package name differs from upstream only by vendor, a composer update can quietly change behavior, or the fork can disappear from Packagist entirely. Pin an exact version and mirror the repo internally, or vendor the diff as a patch. Never rely on dev-master.
• Abandonment is transitive. Upstream FOSUserBundle is itself legacy. Even a well-maintained fork inherits deprecated Symfony security APIs (UsernamePasswordFormAuthenticationListener, getEncoder()) that have been removed in current Symfony. Expect a hard blocker if you try to run it on Symfony 6/7.
• Namespace mismatch is the #1 first-hour bug. Copying upstream docs produces use FOS\UserBundle\... while the fork may declare Nmalo\FOSUserBundle\.... Always confirm from vendor/*/composer.json → autoload.psr-4 before debugging anything else.
• No Laravel auto-discovery. There is no extra.laravel.providers. Even if Composer installs it, Laravel will not register anything. If you got it to install, that is not a sign it works.
• Eloquent vs Doctrine. FOSUserBundle's UserManager is repository-oriented and returns Doctrine entities. There is no Model base that plays well with Illuminate\Database\Eloquent\Model; you would be writing adapters for every read and write, for zero gain over Laravel's built-in Auth guards.
• Debugging auth failures. In Symfony, bin/console debug:container fos_user.user_manager and debug:event-dispatcher (looking for fos_user.* listeners) will tell you whether the bundle is actually wired. If the bundle is not registered, routes 404 and the firewall silently falls back to anonymous.
• Config quirks. firewall_name must match a firewall in security.yaml, and db_driver: orm is the only sane value — mongodb/couchdb drivers in the Model layer are largely unmaintained in forks. Also watch registration.confirmation.enabled: if it is on without a working mailer service, registration silently appears to succeed while accounts stay disabled.
• Extension points to prefer, in order: event subscribers → UserManager decoration → service config overrides → template override → controller subclass. The further down that list you go, the more you pay on every upstream/fork change.
• Recommendation for the assessment: for a Laravel codebase, do not adopt this. For a legacy Symfony codebase, keep it running behind a plan to migrate to symfony/security-bundle authenticators, and budget for that migration rather than for maintaining the fork.