Forgot Password Bundle Laravel Package

Getting Started

This is not a Laravel package — it's a Symfony2-era bundle (a fork of coop-tilleuls/forgot-password-bundle). Before writing a single line of Laravel code, decide where it will live:

1. Confirm the target runtime. The bundle expects a Symfony kernel, AppKernel/bundles.php registration, and Symfony's DI container. It will not autoload or boot inside a Laravel app without a compatibility shim. If your app is pure Laravel, treat this repository as a reference implementation, not a dependency.
2. Read these files first, in order:
   • README.md — the public contract (routes, config keys, events).
   • DependencyInjection/Configuration.php — every config knob (password_request_entity_class, user_entity_class, token TTL, mailer).
   • Controller/ForgotPasswordController.php — the two endpoints: request-a-token and reset-with-token.
   • Mailer/ + Event/ — the extension surface most forks touch.
3. First use case: POST /forgot-password with a username/email → generate a token, persist a PasswordRequest, email a reset link → POST /forgot-password/{token} with a new password → fire a reset event.

If you are maintaining a legacy Symfony service that already has this bundle, the minimal path is: composer require imaximius/forgot-password-bundle, register the bundle, import its routing, map your User entity in config, and provide a mailer implementation. In a Laravel-only codebase, skip the install and map the concepts onto Laravel's native Password broker (sendResetLink, reset, passwords table) — you get the same flow with far less surface area.

Implementation Patterns

Core Symfony workflow (if you must run the bundle directly):

• Configure a password_request_entity_class (usually your own entity extending the bundle's base) and a user_entity_class.
• Set token_ttl deliberately (short — 15–60 minutes) and wire your own MailerInterface implementation, because the default is a no-op/stub.
• Hook ForgotPasswordEvents (REQUEST_PASSWORD, RESET_PASSWORD, invalid-token events) to invalidate sessions, log attempts, or trigger "password changed" notifications.
• Secure the reset endpoint behind a firewall that is anonymous: true for the request route but restricts the reset route to a signed/validated token.

Laravel-native equivalent (recommended for day-to-day):

// Request
Password::sendResetLink($request->only('email'));

// Reset
Password::reset($request->only('email','password','password_confirmation','token'), function ($user, $password) {
    $user->forceFill(['password' => Hash::make($password)])->save();
    event(new PasswordReset($user));
});

Override App\Models\User::sendPasswordResetNotification() to point at a custom ResetPassword notification so you control branding, expiry text, and the signed URL. This is the pattern the bundle is emulating; use it unless you are contractually locked into Symfony.

Integration tips if you keep both worlds:

• Expose the bundle's endpoints as an internal HTTP service and call it from Laravel via a queued job, keeping the mailer and token tables in the Symfony database. This avoids porting entity logic.
• Mirror the bundle's PasswordRequest concept as a Laravel table (password_resets is already there) so analytics and rate-limiting can be shared.
• Put both flows behind the same rate limiter (Laravel's RateLimiter or Symfony's login_throttling) so token-guessing and email-enumeration behavior is consistent.

Gotchas and Tips

• It is a 2021 Symfony2 bundle with 0 stars. No security advisories, no active maintenance, and Symfony2 is EOL. Do not introduce it into a new Laravel or Symfony 6+ project without a fork and an audit. Treat "imaximius" as an unverified fork of coop-tilleuls/forgot-password-bundle — diff it against upstream before trusting it.
• Default mailer is inert. The bundle does not send email out of the box; you must implement MailerInterface. A silent no-op mailer is the most common "forgot password doesn't work" report.
• Email enumeration. The request endpoint will often leak whether an account exists via 404 vs 200. Return the same response regardless of outcome and rate-limit by IP + identifier.
• Token handling. Verify how the token is stored (plaintext vs hashed) and always enforce single-use + TTL server-side. Never trust the token from the URL alone; validate against the persisted PasswordRequest and mark it consumed inside the same transaction as the password update.
• Config quirks. The bundle's config tree is strict — unknown keys fail container compilation. If you override the controller or entity, you must also update the DI alias, or you'll silently get the bundle default.
• Firewall/routing collisions. Importing the bundle routing can shadow your own /forgot-password route; check bin/console debug:router (Symfony) or php artisan route:list (Laravel if proxying).
• Extension points worth knowing: the mailer interface, the manager service, the event dispatcher, and the PasswordRequest entity. Anything beyond that is fighting the framework.
• Debugging strategy: in Symfony, debug:container CoopTilleulsForgotPassword and check the event listeners; in Laravel, log Password::sendResetLink response constants (RESET_LINK_SENT, INVALID_USER, RESET_THROTTLED) — that status code is where 90% of issues surface.
• Bottom line for a Laravel developer: use this repository as a spec for the flow, implement it with Laravel's password broker, and only reach for the bundle if you are explicitly maintaining the Symfony service it was written for.