Authen Laravel Package

Getting Started

Install the package and confirm it resolves against your Laravel version — v3.1.0 is the release that added Laravel 10 support, so that's the minimum version to target on a modern app:

composer require laravie/authen:^3.1
php artisan vendor:publish --provider="Laravie\Authen\AuthenServiceProvider"

Pin ^3.1 explicitly. Anything below it predates the Laravel 10 compatibility work and will fight illuminate/* constraints on install.

The first places to look:

1. vendor/laravie/authen/src/ — find the service provider, any route files, and the config class. This tells you what the package registers and what it expects from your app.
2. config/authen.php (if published) — guards, providers, route prefixes, middleware, and redirect targets usually live here.
3. vendor/laravie/authen/routes/ — confirm which routes it registers and whether they collide with your existing auth scaffolding.
4. composer.json of the package — verify the illuminate/* constraints now include ^10.0, and note the PHP floor it implies (Laravel 10 means PHP 8.1+).

A good first use case is a minimal login/logout flow on a fresh Laravel 10 app:

• Configure a web guard with an Eloquent user provider in config/auth.php (the package builds on this, it doesn't replace it).
• Point the package's route prefix at something like /auth so it doesn't fight with Breeze/Jetstream defaults.
• Log in a seeded user, hit an auth-middleware-protected route, and verify session persistence and logout behavior.
• Then wire the same flow into an existing app's User model to confirm provider compatibility.

Don't build account management on top until the basic guard round-trip is proven.

Implementation Patterns

Use the package as a thin layer over Laravel's native auth, not a parallel system. The value here is reusable flows and routes on top of guards/providers, so keep your config/auth.php as the source of truth and let the package configure around it.

Guard-per-audience pattern. For apps with multiple user types (e.g. users and admins), define separate guards and providers in config/auth.php, then route each through the package's flows with distinct middleware groups and redirect targets. This is the pattern that pays off day-to-day — one package, multiple entry points.

Route group + middleware integration. Register the package routes behind your own middleware group so you control throttling, locale, and CSRF in one place:

Route::middleware(['web', 'throttle:login'])
    ->prefix(config('authen.prefix', 'auth'))
    ->group(function () {
        // package-provided routes, or your own controllers calling Auth::attempt()
    });

Custom user provider as the extension seam. When you need non-Eloquent users (API tokens, external identity, multi-tenant DB), implement a UserProvider and register it in config/auth.php, then let the package's flows resolve through it. This keeps the package untouched and your logic testable.

Container extension. Bind custom implementations (user resolver, post-login redirector, credential validator) in an AppServiceProvider rather than editing vendor code. The package advertises container extensibility — use it as the override mechanism for anything opinionated.

Testing pattern. In feature tests, use $this->actingAs($user, 'web') for protected-route tests, and separately assert the login flow itself with post('/auth/login', [...])->assertRedirect(...). Session regeneration and remember-me are the two behaviors worth explicit assertions. With Laravel 10's PHPUnit 10 default, check the package's own test suite conventions if you plan to contribute.

Integration with existing scaffolding. If Breeze/Jetstream is already installed, either disable its auth routes or point the package at a different prefix. Running two login route sets is the most common source of confusing 302s.

Upgrade path into the Laravel 10 support. If you were already on an older 3.x tag, this release is additive — no config keys or guard semantics changed, just widened framework constraints. Bump the constraint, run composer update laravie/authen, clear caches, and re-run the login round-trip test.

Gotchas and Tips

• Laravel 10 is supported as of v3.1.0 — Laravel 11 is not. The release notes only mention Laravel 10, so treat 11+ as unverified until a newer tag appears. Pin ^3.1 and gate any future framework upgrade behind an auth-flow test in CI.
• Release cadence is slow. Even with the Laravel 10 fix, assume long gaps between tags. Budget for the possibility that the next major framework bump arrives before the package does, and keep a fallback plan (your own controllers calling Auth::attempt()) if that becomes blocking.
• config:cache surprises. If you publish config and later change guard/provider settings, always php artisan config:clear in local dev. Stale cached auth config produces "credentials don't match" bugs that look like password issues.
• Route collisions. Run php artisan route:list --path=auth after install. Overlapping login/logout URIs silently shadow each other depending on registration order.
• Session regeneration and logout. Confirm the package regenerates the session on login and invalidates it on logout. If it delegates to Auth::attempt() and Auth::logout(), you're fine; if it wraps them, check explicitly — these are security-critical.
• Debugging auth failures. Log Auth::guard('web')->getProvider() and the resolved guard config, and check Auth::attempt() return values plus Auth::guard()->getLastAttempted(). Most issues are provider model mismatch or missing password in the credentials array.
• Remember-me and guard names. Remember-me cookies are scoped per guard name. If you rename a guard, existing remember tokens stop working — plan a migration or accept re-login.
• Don't fork for small changes. Use the container and config for customization; keep vendor untouched so future patches (even rare ones) apply cleanly.
• Security review before production. Because the repo is not easily verifiable here, review password hashing (should defer to Hash), rate limiting on login, and redirect validation on intended() URLs before shipping.