Authentication Laravel Package

Getting Started

amethyst/authentication is not a Laravel package — it is a component of the Amethyst PHP framework, built on top of the Symfony Security primitives (symfony/security-core / security-http). Treat it as a library you wire into Laravel manually rather than something composer require drops into config/app.php for you.

Minimal steps:

1. composer require amethyst/authentication and confirm the transitive Symfony Security version it pulls in does not collide with anything already in your composer.lock (composer why symfony/security-core).
2. Before writing code, read in this order: composer.json (to see the exact Symfony Security major it targets and the required PHP version), then src/, then the tests/ directory — with a package at this maturity level the tests are the most reliable documentation you will get.
3. Register the package's services in a ServiceProvider of your own. The package expects a PSR-11 container (it was written for Amethyst's container), so you will be binding its managers and providers into Laravel's container explicitly.
4. First use case to prove it works: authenticate a single user by username/password against an Eloquent-backed provider and inspect the resulting token/identity object. Do not attempt to replace Laravel's Auth facade on day one — build the smallest possible path first.

Implementation Patterns

Bridge the user provider, don't rewrite it. The package authenticates against a Symfony UserProviderInterface. Write one adapter class that loads your App\Models\User by identifier and returns an object implementing Symfony's UserInterface (or the package's own user contract if it ships one). Wrap App\Models\User rather than making it implement the interface directly — Symfony Security's contract has method names (getUsername, getRoles, eraseCredentials) you don't want leaking into your domain model.

Wrap it in a custom Guard if you want Auth::user() to work. The cleanest integration is a class implementing Illuminate\Contracts\Auth\Guard that delegates attempt(), user(), and check() to the package's authentication manager, then register it in config/auth.php as a custom driver via Auth::extend(). This keeps your controllers idiomatic while the package does the credential verification.

Use it as a parallel stack, not a replacement. The realistic day-to-day pattern is: Laravel's native auth for the web guard (sessions, remember-me, password resets), and this package for a narrower concern — e.g. an API surface where you control the token issuance, or a subsystem where you need Symfony-style roles/voters. Do not run two session-based auth mechanisms over the same routes; that is where the debugging pain starts.

Service provider wiring. In register(), bind the package's authentication manager as a singleton and bind the user provider adapter to the interface the package type-hints. In boot(), publish nothing (there is no config file to publish) and register your guard extension. Keep this in one small provider so it's trivially removable.

Testing. Because the package is Symfony-Security-shaped, you can unit test your adapter against Symfony\Component\Security\Core\User\InMemoryUserProvider without touching the database. Reserve full HTTP tests for the guard, and assert on Auth::check() / Auth::id() rather than on the package's internal token objects.

Gotchas and Tips

• Zero stars, zero dependents, effectively unmaintained. Pin the exact version in composer.json, commit your lockfile, and assume you own the code. If a Symfony Security major bump breaks it, you will be the one patching. Budget for that before adopting.
• No Laravel integration points exist. No facade, no publishable config, no auto-discovery, no Artisan commands. Any convenience you want, you build.
• Session handling is the trap. Symfony Security's HTTP layer has its own session/token-storage semantics. If you let it touch the same session Laravel uses, you will get users appearing logged-in on one guard and not the other, or tokens surviving Auth::logout(). Prefer stateless usage (explicit token per request) over session-backed usage inside Laravel.
• The exception types are Symfony's. AuthenticationException, BadCredentialsException, UsernameNotFoundException — not Laravel's ValidationException. Catch them at your guard boundary and translate to whatever your app's error contract is, or your login endpoint will 500 instead of returning a 422.
• PHP version and extension requirements come from the Symfony Security version underneath, not from the package's own README. Check composer.json's require block before assuming it runs on your PHP 8.3 CI image.
• Debugging tip: the package's failure modes are usually container-binding failures (an interface bound to nothing, or bound as a transient so the manager and the guard get different provider instances). If authentication silently fails, check bindings with app()->bound(...) and prefer singleton() for anything stateful.
• Extension points worth knowing: the user provider (swap it), the encoder/password hasher (swap it to Laravel's Hash so passwords stay consistent with the rest of your app), and the authentication manager itself (wrap it rather than extend it, so upgrades stay cheap).
• Hard rule: never store passwords hashed by two different systems. If any users can log in through both Laravel's guard and this package, funnel both through Illuminate\Hashing\Hasher via a custom encoder.