Laravel Auth Laravel Package

Getting Started

Before you do anything else: this package is archived and unmaintained. Open composer.json in the repo and compare its laravel/framework and illuminate/* constraints against your app. If you're on Laravel 8+, expect to either pin an old Laravel, vendor-fork the package, or walk away. For most greenfield work, the honest first move is to look at what you're trying to get (RBAC + 2FA + social) and ask whether Fortify + spatie/laravel-permission + Socialite covers it with less risk.

If you're committing anyway — typically to maintain an existing app built on it — the first-day steps are:

1. composer require rinvex/laravel-auth (pin the exact version; nothing here will get upstream fixes).
2. Publish the config and migrations: php artisan vendor:publish --tag="rinvex-auth" and --tag="rinvex-auth-migrations" (confirm tag names with php artisan vendor:publish listing — they've shifted across releases).
3. Inspect the published config/auth.php-adjacent config file immediately. It controls models, tables, guards, features (2FA, social, verification), and middleware. This is the real source of truth for how the package behaves in your app.
4. Run migrations against a scratch database first. The package adds role/ability/permission tables alongside — or sometimes in competition with — your default users table.
5. Adopt the package's User model or apply its traits (HasRoles-style traits for role/ability checks, plus auth-related traits) to your existing model. Read the trait source before trusting it.

First use case to prove out: take a stock Laravel User, attach the traits, seed two roles (admin, member), assign one, and gate a route with the package's role middleware. If that works end-to-end in an hour, the rest (2FA, social) is a sequence of similar wiring jobs. If it doesn't, stop — the cost of debugging an abandoned auth layer compounds.

Implementation Patterns

RBAC as your authorization backbone. The package exposes roles, abilities/permissions, and the pivot relationships between them. The daily pattern is: define abilities at seed time (or via a migration), attach them to roles, attach roles to users, then check with $user->hasRole(...), $user->can(...), or via Laravel's Gate. Prefer registering the package's checks with Gate::before / Gate::after so @can and $this->authorize() keep working — you don't want a second, parallel authorization vocabulary in your controllers.

Middleware for coarse checks, policies for fine ones. Use the package middleware for "is this user in admin?" at the route group level. Keep resource-level rules (can this user edit this post?) in Laravel policies; the package shouldn't own that logic. Mixing the two is where teams get confused.

2FA as an explicit flow. Model it as three states — disabled, pending verification, enabled — and store the secret only after the user successfully verifies a code. Wire it into login via an event/listener or a middleware that checks the 2FA column on the user and redirects to a challenge route. Never let the login response complete before the TOTP check; the package's traits give you the primitives, not the full UX.

Social auth via Socialite, not via the package's abstractions alone. Configure providers in the package config, but be prepared to call the package's social callback handling directly. Map provider identities to local users deliberately — decide up front whether you auto-create users on first social login and how you handle email collisions with existing accounts.

Verification (email/phone) as a trait concern. Treat it like Laravel's MustVerifyEmail: a column, a middleware, and a resend route. The package's verification pieces are the storage and token handling; the routing and throttling are yours.

Testing. Because the authorization surface is trait methods, unit tests are cheap: build a user, assign roles, assert hasRole/can. Integration tests for 2FA need a fake TOTP secret and clock control — pin the secret in a factory state rather than generating one per test.

Gotchas and Tips

• The archive is the biggest gotcha. No security patches, no Laravel major-version support. If you must keep it, fork it into your org, tag your own release, and add a CI matrix. Treat it as internal code you happen to have inherited.
• Migration collisions. The package's migrations may assume the default users schema. If you've customized columns or use UUIDs, edit the published migrations before the first migrate rather than patching after.
• Model substitution is global. Changing the configured user/role model after you've got data is painful — foreign keys and polymorphic/morph references bake in table and class names. Decide before you seed.
• Config cache bites. Because behaviour lives in config (features on/off, guards, providers), a stale php artisan config:cache after changing the config file is a classic "why is 2FA suddenly disabled?" moment. Clear it in deploy scripts.
• Guard mismatches. The package registers its own middleware and may assume the web guard. If you're behind api/Sanctum, verify the guard is threaded through both the config and your route definitions; otherwise auth middleware passes while the package's checks see an unauthenticated user.
• Permission caching. If the package caches abilities per user, tests and role changes will look wrong until the cache is cleared. Look for a cache key or forget/reset method in the source and call it explicitly after seeding or after an admin edits roles.
• Trait name drift. Trait and method names have changed between releases. Don't trust blog posts; read the trait files in vendor/rinvex/laravel-auth/src/. This is the single fastest way to answer "does this method exist?"
• Debugging authorization. Use php artisan tinker to dump $user->getRoles() / permission collections, and temporarily register a Gate::before logger. Route-level php artisan route:list --path= confirms middleware order.
• Extension points. Published config, published migrations, and the traits themselves (you can override methods in your own model via use Trait { method as protected; } aliasing) are your levers. Prefer overriding in your User model over editing vendor files — but since vendor is frozen, a fork is more honest than a shim.
• Don't let 2FA ship half-done. Partial 2FA (secret stored, verification optional) is worse than none. Gate the login completion on the verified column, and provide recovery codes from day one.