User Bundle Laravel Package

Getting Started

The first thing to know: this is a Symfony bundle, not a Laravel package. If you're in a Laravel codebase, there's no drop-in path — you'd be reviewing it for patterns (user manager/repository separation, lifecycle hooks) to port, or you're actually working in a Symfony project. In a Symfony app:

1. composer require useperform/user-bundle
2. With Symfony Flex it should auto-register; otherwise add Perform\UserBundle\UserBundle to config/bundles.php
3. Open the bundle's DI extension (DependencyInjection/*Extension.php) and config tree first — that tells you which services are configurable and what the user class default is
4. Point security.yaml at the bundle's user provider (or your subclass), then set provider on your firewall
5. First use case: swap the default generated User entity for the bundle's User class, run doctrine:migrations:diff + migrate, and hit the login route

The README (not the source) should be your first lookup for the exact namespace of the User entity, any required interfaces, and the bundle alias used in config.

Implementation Patterns

• Subclass the User entity. Add app-specific fields in your own App\Entity\User extends Perform\...\User rather than editing vendor code, then register your class in the bundle config. Keeps the manager/repository logic intact.
• Override services, don't fork. Redeclare the user manager, password encoder, or event listeners in config/services.yaml with the same service id. This is the standard Symfony escape hatch and works even when the bundle is undocumented.
• Wrap the manager in a domain service. For multi-tenant or soft-delete requirements, compose the bundle's manager inside your own service that adds scoping — cleaner than fighting the bundle's repository.
• Template/route overriding. If it ships controllers and Twig templates, override via templates/bundles/<BundleName>/ and swap in your own controllers in routes.yaml while keeping the bundle's forms.
• Event listeners over base-class overrides. If the bundle dispatches user lifecycle events (pre-persist, post-register), hook those instead of overriding the manager — more upgrade-safe.

Gotchas and Tips

• Zero stars and zero dependents means treat it as experimental: pin an exact version ("x.y.z" not "^x.y"), review the source before production, and don't assume semantic versioning discipline.
• Symfony version drift. Check composer.json's symfony/* constraints against your app's composer.lock. A bundle this young is likely tested against one minor line only.
• Doctrine mapping conflicts. Auto-mapping the bundle's User plus your subclass is the most common first failure — run doctrine:schema:validate and check for duplicated table/column names after subclassing.
• Firewall ordering. If login/auth routes 404 or loop, the firewall provider is usually pointing at your subclass but security.yaml still references the bundle's default provider alias.
• Debug the container, not the code. bin/console debug:container --tag=kernel.event_listener and debug:config <bundle_alias> are faster than reading source when wiring is opaque.
• Extension points to probe first: the DI extension's config tree, any *Interface for the user manager/provider, and event classes under Event/. Those are what you build against; everything else is internal.
• If you're a Laravel developer eyeing this for inspiration: the patterns (subclassable User entity, manager + repository split, lifecycle events) map cleanly onto Laravel's Authenticatable model, a UserManager service, and model events — worth borrowing even if you never install the bundle.