User Bundle Laravel Package

Getting Started

This is a small, low-traffic bundle (3 stars, 0 dependents), so treat the source as the primary documentation and budget time to read it before wiring anything up.

1. Install: composer require spipu/user-bundle. If there is no Flex recipe, register it manually in config/bundles.php:

   Spipu\UserBundle\SpipuUserBundle::class => ['all' => true],
   

   Confirm the actual namespace from the package's composer.json autoload.psr-4 before you copy this.

2. Look here first, in order:

   • README.md for the intended integration path.
   • src/DependencyInjection/Configuration.php — this is the authoritative list of config keys, defaults, and required nodes. Anything the README omits will be here.
   • The provided user entity / mapped superclass and the user manager service, to understand what you inherit vs. what you must implement.
   • src/Resources/config/services.yaml for service IDs and aliases you can autowire.

3. Create/adapt your App\Entity\User. Most bundles of this shape either ship a User entity you configure directly or a MappedSuperclass you extend. Extend it, add your own Doctrine mapping (#[ORM\Entity], #[ORM\Table]), and let the bundle own auth-related fields and behavior.

4. Configure minimally in config/packages/spipu_user.yaml (exact keys from Configuration.php): the user class, table name, and any field/column overrides.

5. Wire Symfony Security to the bundle's entity:

   security:
     providers:
       users:
         entity: { class: App\Entity\User, property: email }
   

6. First use case — register and authenticate a user: inject the bundle's user manager (or repository), create a user, set the plaintext password through the manager so it hashes it, persist, then log in through a standard form_login firewall. That end-to-end path is the fastest way to validate the bundle's assumptions about your entity and provider.

Implementation Patterns

• Always go through the manager for password changes. Bundles like this usually hash inside createUser()/updatePassword(). Setting $user->setPassword($plain) directly bypasses hashing; setting a pre-hashed value in a manager method will double-hash. Check the manager's implementation once and standardize on it.
• Constructor injection, not container lookups. Inject the manager/repository interface (or its service alias) into controllers and handlers. This makes swapping in your own implementation trivial if the bundle's is too thin.
• Registration flow: controller → form/DTO with NotBlank/Length/PasswordStrength constraints → manager createUser() → persist/flush → optional domain event (UserRegisteredEvent). Keep password hashing out of the controller.
• API auth: pair the bundle with json_login (session/token) or a JWT/lexik layer. The bundle typically only owns user data and hashing, not token issuance — don't expect it to ship token endpoints.
• Profile updates: treat email/username changes as a separate workflow from password changes so you can trigger verification/re-hash independently.
• Doctrine migrations: after you map the concrete entity, run bin/console doctrine:migrations:diff and commit the migration. Do not rely on schema:update in any shared environment.
• Testing: because there are no dependents and no battle-testing, write your own unit test for the manager plus a functional test for registration + login. Mock the manager in controller tests; assert on a real in-memory SQLite schema for the entity.
• Extension points to prefer: config keys from Configuration.php, service decoration/overriding via services.yaml, and subclassing the provided entity. Avoid editing vendor code — there will be no upgrade merge path.

Gotchas and Tips

• Manual bundle registration is the #1 first-run failure. If you get "service not found" or your config file is ignored, check config/bundles.php and run bin/console cache:clear.
• Mapped superclass vs. concrete entity. If the bundle ships a mapped superclass, you must define your own #[ORM\Entity] class extending it; forgetting this yields "not a managed entity" errors at runtime, not at cache-warm time.
• Password hashing mismatches manifest as "invalid credentials" with no error — verify the manager is the only place passwords are set, and that the security provider's property matches the field you actually populate (email vs. username).
• Config cache. Changing bundle config requires cache:clear; stale config is a common false positive when debugging.
• Sparse docs and tiny surface area. With 3 stars and no dependents, assume edge cases are undocumented. Read Configuration.php and the services definitions before guessing key names; grep the source for the exception messages you hit.
• Pin the version. "spipu/user-bundle": "^X.Y" with a committed composer.lock. A low-adoption package can change config keys between releases without a deprecation path; a wildcard constraint is a liability.
• Namespace verification. Confirm the PSR-4 namespace from composer.json rather than trusting examples online — small bundles get renamed.
• Debugging tip: use bin/console debug:container | grep -i user and debug:config spipu_user (if an extension alias exists) to see what actually got registered.
• Extension points exist but are thin. Plan to wrap the manager in your own service if you need cross-cutting concerns (audit logging, invitation flows, soft deletes); don't fork the bundle for that.
• Last release timing. The listed release date is recent relative to typical maintenance cadences; check the git log for actual activity and issue responsiveness before committing to it as core infrastructure rather than a starting scaffold.