Download the PHP package bbs-lab/laravel-password-rotation without Composer

Laravel Password Rotation

Password rotation for any Laravel application — no admin panel required. Force any authenticatable model to rotate its password every N days, with reuse prevention, a first-login gate, an expiry-warning helper and a redirect middleware. No Nova, no Filament.

This is the shared core behind the two admin-panel twins:

• bbs-lab/nova-password-rotation — Laravel Nova
• bbs-lab/filament-password-rotation — Filament

The rotatable subject is not tied to the User model: everything keys off the MustRotatePassword interface on whatever authenticatable you gate, and the password history is polymorphic, so any model works.

Requirements

• PHP ^8.2
• Laravel ^11.0 || ^12.0 || ^13.0

Installation

The service provider auto-registers via Laravel package discovery.

The password_histories table migrates automatically. Publish the config and the (review-before-run) user-column migration, then migrate:

Usage

Make a model rotatable

Implement MustRotatePassword and use the RotatesPassword trait on any authenticatable model. Nothing is tied to User — the trait keys off the interface and the history table is polymorphic.

The trait stamps password_changed_at whenever the password changes, records each hash for reuse prevention, and dispatches PasswordRotated. It exposes:

• passwordHasExpired(): bool — past the rotation window (or never set, when force_on_first_login is on)
• passwordIsExpiring(): bool — inside the warning window (warn_days)
• passwordExpiresAt(): ?CarbonInterface

Force expired users to a change screen

Add EnsurePasswordIsNotExpired to the middleware group that guards your app and point redirect_route at your own password-change screen:

An expired user is redirected to redirect_route on every request except that route and anything in except_routes. Exempt your logout route (and, if the change form POSTs to a different route, that route too) or the user is trapped with no way out. The middleware reads the default guard's user; on a custom guard, wire it accordingly.

Bypass rotation per request (e.g. SSO users)

Some users must never be forced through the local change screen — SSO users, for instance, whose password lives in the identity provider. Register a bypass callback via the PasswordRotation facade (in a service provider's boot()). It receives the request and the expired user, and returning true lets that request through:

• Register the callback in code, not in the config file — a Closure there would break php artisan config:cache.
• Guard hasSession() before reading the session so the callback is safe if the middleware ever runs outside the web group (a token/API guard has no session). Store the SSO marker as a real boolean (session(['sso' => true])).
• bypass() may be called several times; the request is exempt as soon as any callback returns true.

Prevent password reuse

Add the PasswordNotReused rule to your change-password validation:

It rejects the current password and the last history_count hashes.

Report on rotation status

The command scans the classes listed under models in the config.

License

The MIT License (MIT). Please see License File for more information.