User Bundle Laravel Package

Getting Started

The README is a stub: this repository is a read-only subtree split of the main enhavo/enhavo monorepo. Treat it as a Composer installable slice, not a place to browse issues, open PRs, or read docs. Your first stop should be the main repository (and its demo app), then the bundle source under src/Enhavo/Bundle/UserBundle in that monorepo.

Minimal install:

composer require enhavo/user-bundle

Register the bundle (Symfony Flex may do this automatically) and its usual companions — Enhavo bundles are rarely standalone:

// config/bundles.php
Enhavo\Bundle\UserBundle\EnhavoUserBundle::class => ['all' => true],
Enhavo\Bundle\ResourceBundle\EnhavoResourceBundle::class => ['all' => true],
Enhavo\Bundle\DoctrineExtensionBundle\EnhavoDoctrineExtensionBundle::class => ['all' => true],
// plus admin/theme/routing bundles as needed

Then work through this order:

1. Inspect the bundle's own config. Look for DependencyInjection/Configuration.php and the Resources/config/*.yaml files in the installed vendor directory. That is the real documentation for available options (enhavo_user: root key, class overrides, route prefixes, mailer settings).
2. Wire security. The bundle ships a user entity/model and expects a firewall in config/packages/security.yaml pointing at its user provider and login/logout routes. Check Resources/config/routing.yaml (or the Routing folder) for the route names it exposes.
3. Run migrations. The bundle provides Doctrine mappings for users, groups, and typically reset-token tables. Confirm with bin/console doctrine:mapping:info that the entity classes were picked up, then bin/console doctrine:migrations:diff / migrate.
4. Create a first user. Either via a fixture/console command from the bundle or by seeding the table directly, then log into the Enhavo admin.

First realistic use case: enable the admin CRUD for users and groups so editors can manage accounts, then add frontend login/registration. That covers the 80% path: resource config in config/packages/enhavo_*.yaml, a firewall, and the bundle's controllers/templates.

Implementation Patterns

Extending the model, not editing it. The bundle's User and Group are designed for Doctrine inheritance or class replacement via config. The standard pattern is to create your own entity extending the bundle's mapped superclass/model and point the bundle's config at it:

# config/packages/enhavo_user.yaml
enhavo_user:
    resources:
        user:
            classes:
                model: App\Entity\User
        group:
            classes:
                model: App\Entity\Group

Your App\Entity\User extends the bundle base class, is marked #[ORM\Entity] with your own table, and adds fields (phone, locale, tenant, etc.). Do this before running the first migration — retrofitting inheritance onto an existing user table is painful.

Use the bundle's manager/repository services rather than raw EntityManager. Enhavo bundles expose resource managers (typically enhavo_user.manager.user or an autowirable UserManager interface). That keeps password hashing, group assignment, and reset-token handling consistent with the admin UI. Fetch through the repository by email/username in your own controllers, but mutate through the manager.

Admin resource configuration. Enhavo's admin is resource-driven. User and group management are declared as resources with routes, form types, and table/grid config in the bundle's YAML. To customise day-to-day (add a column, change a form field, restrict routes by role), override the resource config in your app config or replace the form type via the class override map — don't copy templates into your app unless you must.

Frontend flows. Login, registration, password reset, and profile editing are handled by bundle controllers with their own routes and templates. Typical integration:

• Point your firewall's form_login at the bundle's login route.
• Override templates by placing files at the path the bundle expects under templates/bundles/EnhavoUserBundle/....
• Register a mailer/notification sender for reset and confirmation emails; the bundle usually expects a mailer service or config block.
• Add an event subscriber/listener if you need post-registration hooks (e.g. CRM sync) — prefer listening to bundle-dispatched events over overriding controllers.

Groups and roles. Roles come from Symfony's role hierarchy plus group-assigned roles. Keep the hierarchy in security.yaml, keep grantable roles in the bundle's group config, and use the admin to assign. Don't hardcode role strings scattered through your app — centralise them as constants tied to the group configuration.

Extending the admin UI. For extra user fields, you generally have two options: override the resource's form type (clean, upgrade-safe) or attach a Doctrine extension / lifecycle listener for derived data. Prefer the former.

Gotchas and Tips

• Read-only split. Any issue or pull request must go to enhavo/enhavo. Version tags of this package follow the monorepo release, so pin enhavo/user-bundle to a version compatible with your enhavo/enhavo and Symfony versions. Mismatched Enhavo bundle versions across packages is the most common breakage.
• Not a standalone user system. It assumes Enhavo's resource/admin/doctrine infrastructure and often its asset build. If you only want authentication, this bundle is heavier than symfony/security-bundle alone; expect to pull in several Enhavo dependencies.
• Subtree splits lag. A change merged in the monorepo may not appear in this package until the next split/tag. If you need a fix immediately, use a VCS repository pointing at the monorepo, or a Composer patch.
• Config keys are undocumented here. Always validate against Configuration.php. bin/console config:dump-reference enhavo_user and bin/console debug:config enhavo_user are your fastest paths when something silently defaults.
• Migration ordering with inheritance. When switching to your own User class, generate migrations after configuring the class override and review the diff carefully — Doctrine may try to drop and recreate the table rather than alter it.
• Firewall and route name coupling. If login redirects loop or you get "route not found", check bin/console debug:router | grep -i user and reconcile the firewall's login_path/check_path with actual route names. Also confirm the firewall comes before any catch-all firewall.
• Password encoding. Older Enhavo versions may reference specific encoders/hashers. Align with your Symfony version's password_hashers config; verify existing hashes still validate after upgrades (a rehash-on-login strategy helps).
• Translations and templates. The bundle ships its own translation domain and templates. Override by domain/key rather than editing vendor files; clear cache (bin/console cache:clear) after template overrides, especially in prod with a warm cache.
• Debugging toolkit: debug:container --tag=enhavo.resource, doctrine:mapping:info, debug:event-dispatcher | grep -i user, and reading the bundle's Resources/config files. Because public docs are thin, the vendor directory is the documentation — grep for the service ID or config key you're missing.
• Extension points to prefer, in order: config class overrides → form/table type overrides → event listeners → template overrides → decorating a bundle service. Forking or copying bundle code is a last resort given the split-repo release cadence.