Forgot Password Bundle Laravel Package

Getting Started

First, a reality check: tilleuls/forgot-password-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no config/forgot-password.php, no php artisan vendor:publish. From a Laravel seat, you have three legitimate options: consume it from a Symfony microservice over HTTP, port the three-endpoint pattern into a Laravel controller, or reach for Laravel's built-in Password::sendResetLink instead. The rest of this assessment assumes you're either in a Symfony service or porting the pattern.

To get a working flow:

1. composer require tilleuls/forgot-password-bundle and register CoopTilleulsForgotPasswordBundle in config/bundles.php.
2. Import the bundle routing (annotations or the shipped routing.xml) to expose POST /forgot-password/, GET /forgot-password/{token}, POST /forgot-password/{token}.
3. Implement PasswordResetInterface on your user entity — it needs getEmail()/getPassword() (or the identifier property you configure).
4. Configure the bundle (representative keys):

coop_tilleuls_forgot_password:
    user_class: App\Entity\User
    password_broker: security.user_password_hasher
    token_lifetime: 3600
    from_email: [email protected]

5. Generate and run the Doctrine migration for the token table.

Where to look first: DependencyInjection/Configuration.php (full config surface), Controller/ (the three endpoints you're actually shipping), and Event/ (the only real extension point).

First use case: POST /forgot-password/ {"email":"[email protected]"} returns 204 and emails a GET /forgot-password/{token} link; the GET validates the token; POST /forgot-password/{token} {"password":"..."} completes the flow once you've wired the reset listener.

Implementation Patterns

• Event-driven reset. The bundle does not mutate the user's password by default. You subscribe to the requested / token-validated / token-reset events and, in the reset listener, hash the new password and persist it via your repository or password broker. This is the single most important integration point.
• Custom mailer. Implement CoopTilleuls\ForgotPasswordBundle\Mailer\MailerInterface and alias it in your services config to replace the built-in Symfony Mailer implementation — useful if you want MJML templates, Postmark, or a queued send.
• Async/queue. The default mailer is synchronous. For Laravel-style dispatch semantics, ignore the built-in mailer and dispatch a job from a ForgotPasswordRequestedEvent listener that carries the token.
• Password broker swap. Implement PasswordBrokerInterface to look users up from any store (an Eloquent repository behind a thin adapter, an external IAM, etc.) when you don't want Symfony's built-in provider.
• Rate limiting. The bundle ships none. Apply Symfony's rate limiter to the request route (typically per-IP and per-identifier) or do it at the gateway.
• Testing. Use Symfony's WebTestCase (or zenstruck/browser) for the three endpoints; from Laravel, hit them as ordinary HTTP Feature tests against a running Symfony service.
• Response shaping. Default responses are 204/400. Use a kernel response listener or event listener if you need a custom JSON envelope.

Gotchas and Tips

• Not a Laravel package. No auto-discovery, no Blade mail templates, no Eloquent. Don't expect vendor:publish to do anything useful; budget time for either a bridge or a port.
• Passwords don't change by themselves. The most common bug is getting 204s on every endpoint and assuming the user's password was reset. Until you handle the reset event (hash + persist), nothing is saved.
• Email enumeration. The request endpoint returns 204 regardless of whether the email exists — preserve that property. Custom listeners that log "user not found" to a client-visible channel will leak it.
• Doctrine migrations. Forgetting the token table migration produces opaque table not found errors deep inside the request flow. Add the migration before you test anything.
• Token semantics. Tokens are TTL-bound and single-use; a new request typically invalidates prior tokens (configurable). Watch concurrent requests for race conditions on token invalidation.
• Hash consistency. Whatever hashing you apply in the reset listener must match what your password_broker/login path verifies — otherwise the user resets successfully and immediately can't log in.
• from_email is required. A misconfigured transport surfaces as a 500 on the request endpoint, which is easy to misdiagnose as a token problem.
• Identifier hygiene. User lookup assumes a unique, usually case-insensitive email. Trim and normalize yourself before handing off to the broker.
• Version compatibility. The 2026 release implies Symfony 6.4/7.x; older 5.x pins will drag symfony/security-bundle and make installation painful in modern apps.
• Stay on the extension points. Events, MailerInterface, PasswordBrokerInterface, and route prefix config are the only sane hooks — resist forking controllers.
• Benchmark the Laravel-native option. Password::sendResetLink() / Breeze covers the same UX with zero Symfony dependency. Pick this bundle only if the API is genuinely Symfony and you want its opinionated REST contract.