Fos User Bundle Polyfill Laravel Package

Getting Started

This package is a typing shim, not a feature bundle. It ships the FOS\UserBundle\Model\* interfaces (and related base classes) so legacy code can keep type-hinting them after you remove the real friendsofsymfony/user-bundle. There are no services, controllers, DI extensions, or migrations — install and forget.

Minimal steps:

composer require nucleos/fos-user-bundle-polyfill

Before installing, confirm the problem is actually a missing-interface problem, not a missing-bundle problem:

# Who still references FOSUserBundle?
composer why friendsofsymfony/user-bundle
grep -rn "FOS\\\\UserBundle" src/ vendor/ --include="*.php" | head

Your first realistic use case: a legacy app (or a third-party bundle your app depends on) type-hints FOS\UserBundle\Model\UserInterface in a constructor or method signature. You've already migrated your own User entity to Symfony's UserInterface, but PHP still needs the FOS interface to exist for the type check to pass. Drop in the polyfill, make your User implement both interfaces, and the fatal errors stop without resurrecting the full FOSUserBundle (and its deprecated controllers, forms, and templating).

If nothing in src/ or your composer.lock references FOS\UserBundle\Model, you don't need this package — skip it.

Implementation Patterns

Migration shim. The common workflow is a three-commit migration:

1. Add the polyfill alongside FOSUserBundle.
2. Rewrite your User entity to implement the FOS interfaces directly (the polyfill gives you the contracts; you keep your own fields/getRoles()/getPassword()).
3. Remove friendsofsymfony/user-bundle from composer.json and confirm nothing new breaks.

use FOS\UserBundle\Model\UserInterface as FOSUserInterface;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class User implements UserInterface, PasswordAuthenticatedUserInterface, FOSUserInterface
{
    // your existing properties...
}

Satisfying transitive dependencies. If a package in your tree hard-requires friendsofsymfony/user-bundle only for its interfaces, you can use Composer's provide inside your root composer.json to declare the contract is satisfied, then let the polyfill supply the namespace:

{
  "provide": {
    "friendsofsymfony/user-bundle": "2.1.0"
  }
}

Be conservative with this — it only works if the dependent package never touches FOSUserBundle services at runtime.

Bridge to Symfony Security. Treat the polyfill as the contract layer and Symfony's security-bundle as the runtime layer. Your firewall/provider config should point at your own UserProvider; the polyfill's interfaces only need to exist for signatures and instanceof checks. Modern code should target Symfony\Component\Security\Core\User\UserInterface first and the FOS interface second.

Test harness. Because the polyfill contributes nothing at runtime, your integration tests are the only thing proving the migration is complete. Add a smoke test that instantiates your User, runs a login through the real Symfony firewall, and asserts the FOSUserInterface methods (isSuperAdmin, getUsername, getEmail if present in the shim version) behave as callers expect.

Gotchas and Tips

• Archived since January 2020. No security fixes, no PHP 8.x/8.3 compatibility guarantees, no updates to match later Symfony interfaces (e.g. PasswordAuthenticatedUserInterface, UserInterface::getUserIdentifier()). Treat the version you pin as frozen.
• Interfaces only — no behavior. Do not expect FOS\UserBundle\Model\User or Group base classes to implement password hashing, role hierarchy, or canonicalization. If you relied on FOS base classes doing real work, the polyfill will silently leave those methods as your responsibility.
• Namespace collision. Installing this while the real friendsofsymfony/user-bundle is still present produces duplicate class definitions and confusing autoload failures. Only one can win the FOS\UserBundle\Model namespace — the archive's autoload map is not defensive about it.
• Debugging missing methods. If a signature or method is absent from the polyfill's interface (likely, given age), you'll get an Error: Class ... contains abstract method or a fatal. Inspect the shim directly: ls vendor/nucleos/fos-user-bundle-polyfill/src/FOS/UserBundle/Model/ and diff against what your code actually calls.
• Don't confuse with nucleos/user-bundle. That's the maintained successor project. The polyfill is only for keeping the old FOS namespace alive — if you're starting greenfield, skip both and use Symfony's native user system.
• Composer provide/replace is a foot-gun. Using it to silence a hard dependency works only if the dependent package never instantiates FOS services. Audit its usages of FOS\UserBundle\Model\* beyond type hints before trusting it.
• Zero dependents, tiny star count. Assume the package is untested against your specific Symfony version. Budget time for a quick bin/console cache:warmup and a login smoke test after adding or removing it — that's your real integration check.