Identity Bundle Laravel Package

Getting Started

Reality check first. fastfony/identity-bundle is a Symfony bundle, not a Laravel package. If you're a Laravel developer, "day-to-day leverage" splits into two honest scenarios: you're maintaining or integrating with a Symfony service (then this is directly usable), or you're looking for a Laravel auth/roles/groups solution (then this is a reference model, not a dependency). Do not try to composer require this into a Laravel app — it will pull Symfony security/Doctrine contracts and fight Laravel's container.

Concept translation table (useful before you read any of the code):

Minimal Symfony-side steps (verify exact names against the README and composer show; the package is low-adoption, so trust the source over blog posts):

1. composer require fastfony/identity-bundle in a Symfony 6/7 app with Doctrine ORM and symfony/security-bundle present.
2. Let Flex register the bundle, or add it to config/bundles.php manually.
3. Inspect config/packages/ for the bundle's config file; the package almost certainly expects a configurable user entity class. Set it to your app's User entity.
4. Run php bin/console doctrine:migrations:diff and review the generated schema before applying — do not assume the bundle ships migrations you want verbatim.
5. Confirm the firewall in security.yaml points at the bundle's user provider.

Where to look first: the bundle's DependencyInjection/Configuration.php (tells you every knob it actually supports), then its entity/repository classes, then Resources/config/services.php. That trio tells you more than the README will.

First use case: a "group grants a role" flow — create a group, attach roles to it, assign users to the group, and check authorization with $this->isGranted('ROLE_X') in a controller. That single path exercises the entity relations, the repository queries, and the security integration at once, which is the fastest way to know whether the bundle fits.

Implementation Patterns

Centralize role names as constants. The moment roles live in the database and in security.yaml and in string literals in controllers, you have three sources of truth. Define App\Security\Roles::ADMIN etc., seed the DB from those constants, and reference the constants in access checks and voters.

Treat groups as role bundles, not as a second permission system. The clean pattern is: User -> Groups -> Roles -> Voter checks. Groups should never be checked directly in authorization logic; resolve a user's effective roles through their groups and let voters work on roles only. This keeps the model portable if you later rewrite it in Laravel with spatie/laravel-permission teams.

Seed, don't hand-create. Write a fixture or a console command that creates the baseline roles and groups idempotently. Day-to-day, every environment (test, staging, prod) needs the same role skeleton, and hand-clicking an admin UI for that is how you get drift.

Wrap role assignment in a service, not controllers. A small IdentityManager (assign group, revoke role, resolve effective roles) gives you one place to fire events, clear caches, and audit. It also becomes your seam if you swap the bundle out later.

Use the security voter as the integration boundary. Don't call isGranted('ROLE_ADMIN') scatter-shot. Write attributes like POST_EDIT and have one voter that consults effective roles. If you ever port to Laravel, that voter maps 1:1 onto a Policy.

If you're the Laravel side of a mixed stack: mirror the bundle's model in Eloquent deliberately — users, roles, groups, group_role, group_user pivots — and sync from the Symfony service via an API or a queue message rather than a shared database. Shared ORM schemas across frameworks are a durable source of pain (see Gotchas).

Testing pattern: load a fixture user per role tier (guest, member, group-admin, super-admin) and assert authorization on each route. This is cheap and catches role-hierarchy misconfiguration immediately, which is the most common wiring bug in bundles like this.

Gotchas and Tips

• Ecosystem risk is the headline. One star, zero dependents, and a release date that reads as a placeholder. Assume no community answers, no Stack Overflow coverage, and no third-party tutorials. Budget time to read the source, and pin the exact version in composer.json — an unpinned minor bump from a single-maintainer package is a real regression vector.
• Doctrine is non-negotiable. If your app uses an alternative persistence layer, or you're a Laravel dev hoping to reuse the entities, you'll be re-implementing them anyway.
• Schema ownership. Bundles that ship user/role entities often assume they own the table names. Check for a configurable table prefix and entity class mapping before writing migrations, or you'll collide with an existing users table.
• Role hierarchy lives in security.yaml, not the bundle. role_hierarchy is Symfony security config; the bundle stores roles but won't expand them for you. If a group assigns ROLE_ADMIN and you expect ROLE_USER to follow, that expansion must be declared in the firewall config.
• Caching. Symfony caches the container and, with it, config. After changing role config or the bundle's YAML, run bin/console cache:clear — a classic "my role change didn't apply" red herring.
• Debugging authorization: use bin/console debug:container --tag=security.voter to confirm the bundle's voter (if any) is registered, and bin/console debug:config <bundle_alias> to see the merged config rather than what you think you wrote.
• Extension points to prefer: a custom user provider and a custom repository are the lowest-risk places to bend the bundle to your needs. Subclassing its entities is riskier — check whether they're final and whether the bundle maps them itself.
• Laravel-side pitfall: if you're porting the concept, don't port the storage model wholesale. Laravel's spatie/laravel-permission will do roles + permissions + teams with a maintained migration path; the only thing worth borrowing from this bundle is the group-as-role-container abstraction, not its schema.
• No dependents means no upgrade canaries. Before a framework upgrade (e.g., Symfony 7.x), check the bundle's composer.json constraint rather than discovering incompatibility at runtime.