Fos User Bundle Adapter Laravel Package

Getting Started

This bundle is a thin glue layer: it lets a user entity managed by FOSUserBundle be consumed by Yucca's core/ACL services. It is not a standalone user system, and it is not a replacement for FOSUserBundle — expect to install both.

1. Confirm prerequisites before anything else. FOSUserBundle is effectively abandoned upstream, so pin everything. You need a Symfony version that still runs FOSUserBundle (typically 4.4/5.4-era) plus the Yucca core packages this adapter depends on. Check vendor/yucca/fos-user-bundle-adapter/composer.json for the exact symfony/* and friendsofsymfony/user-bundle constraints — that file is the most reliable doc you will get, given the package has no dependents and minimal community usage.

2. Install and register.

composer require yucca/fos-user-bundle-adapter

If it is not resolvable from Packagist, add the VCS repository explicitly and require a tagged version or dev-main with a commit hash pinned (never a floating branch — see Gotchas).

// config/bundles.php
return [
    // ...
    FOS\UserBundle\FOSUserBundle::class => ['all' => true],
    Yucca\FosUserAdapterBundle\YuccaFosUserAdapterBundle::class => ['all' => true],
];

3. Where to look first. In vendor/yucca/fos-user-bundle-adapter/:

• DependencyInjection/ — what config keys actually exist (there may be very few, sometimes none).
• Resources/config/services.* — the services being registered and, critically, which existing services they decorate or alias.
• Entity/ or Model/ — the base user class or trait your App\Entity\User is expected to extend/use.
• README.md — thin at best; treat the source as authoritative.

4. First use case. The point of the adapter is that a logged-in FOS user is recognized by Yucca's ACL layer. The smallest proof-of-life is: log in via FOSUserBundle's firewall, then assert that a Yucca-aware check resolves the current user correctly.

// controller smoke test
$user = $this->getUser(); // FOS user
$this->assertNotNull($user);
// Whatever your Yucca ACL service exposes — permission/role check:
$this->denyAccessUnlessGranted('ROLE_USER');

If isGranted works and your Yucca services return the expected user identifier, the wiring is correct. Everything else is configuration detail.

Implementation Patterns

Extend the adapter's base user (or use its trait). The adapter almost certainly ships a base class implementing both FOS's UserInterface and Yucca's expected user contract. Your app entity should inherit it rather than reimplementing:

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Yucca\FosUserAdapterBundle\Model\User as BaseUser;

/**
 * @ORM\Entity
 * @ORM\Table(name="fos_user")
 */
class User extends BaseUser
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;
}

If instead the bundle exposes an interface + trait pair, mirror the same idea: implement the interface, use the trait for the plumbing, keep your own $id mapping.

Point FOSUserBundle at the same class. The adapter is only useful if both bundles resolve the same FQCN:

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

# config/packages/yucca_fos_user_adapter.yaml
# (verify key names in the bundle's Configuration.php — they are few)
yucca_fos_user_adapter:
    user_class: App\Entity\User

Keep the security firewall FOS-shaped, let Yucca consume the identity. FOSUserBundle owns authentication (form login, remember-me, password encoding). Yucca should sit downstream as the authorization decision point. Do not let the adapter register a second UserProvider on the same firewall — that produces confusing "user not found" errors after successful login.

Custom user manager override. If you need tenant scoping or a non-Doctrine store, override the FOS fos_user.user_manager and let the adapter pick it up via alias/decorator rather than editing vendor code:

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

Check whether the adapter aliases fos_user.user_manager directly or defines its own yucca.*.user_manager — if the latter, decorate that service instead.

Incremental adoption. If you already ship FOSUserBundle in production, land the adapter as a no-op first (bundle registered, entity extending the base class, no behavior change), run migrations, then flip ACL checks over to Yucca one call site at a time. Removing the FOS layer later is much harder than adding Yucca on top of it.

Test the seam, not the bundle. Unit tests around the adapter itself are low value. Write an integration test (KernelTestCase + an in-memory or test DB) that boots a kernel with both bundles and asserts a real user can be loaded through both stacks.

Gotchas and Tips

Assume no documentation exists. With zero dependents and near-zero score, there is no Stack Overflow coverage and no blog posts. Your primary debugging tools are:

bin/console debug:container --tag=yucca   # find registered services
bin/console debug:container 'yucca' -vvv  # aliases and definitions
bin/console debug:config yucca_fos_user_adapter   # actual merged config

Pin the version to a commit. No dependents means no one notices breaking changes on main. Use a tagged release if one exists; otherwise pin a full SHA in composer.json.

FOSUserBundle abandonment is the real risk, not this bundle. Plan for the eventual migration to Symfony's native UserInterface / PasswordHasher. Keep your App\Entity\User free of adapter-specific business logic so that migration is a class swap, not a rewrite.

Duplicate table / inheritance mapping errors. The classic failure here is your app entity and the adapter's example/mapped superclass both declaring @ORM\Table(name="fos_user") or both mapping $id. Verify with:

bin/console doctrine:mapping:info
bin/console doctrine:schema:validate

Service decoration order matters. If multiple bundles decorate fos_user.user_manager or the security user provider, Symfony applies decorators in registration order. Put the Yucca adapter bundle after FOSUserBundle in config/bundles.php, and after any of your own decorators, then clear cache and re-check with debug:container.

Cache is your worst enemy when wiring changes. After touching bundle registration, entity inheritance, or service config:

bin/console cache:clear
rm -rf var/cache/*

A stale container will keep instantiating the old user class long after you have "fixed" the mapping.

Extension points to prefer, in order: (1) the bundle's own config keys, (2) service decoration, (3) overriding the adapter's services in services.yaml with the same ID, (4) a compiler pass if you need conditional wiring. Avoid extending bundle-internal classes — with no community pressure on this package, internal APIs can change between any two commits.

If the adapter's model does not fit, do not fight it. Given the package's maturity (0.03 score, 0 dependents), a 40-line custom adapter class implementing Yucca's user interface against your own entity is often a safer long-term bet than forking this bundle. Fork only if you are prepared to own maintenance permanently.

Debugging a "user resolves to null in Yucca" symptom: check in this order — firewall provider points at the FOS provider; fos_user.user_class and any adapter user_class config match exactly; your entity actually extends the adapter base class (a silent trait/use mismatch is easy to miss); then run a minimal integration test that loads the user by ID through each stack independently to find which side is broken.