Getting Started

Install with Composer:
```
composer require amin3536/laravel-api-user-provider
```
Package discovery should register the service provider automatically; if you disabled discovery, add Amin3536\ApiUserProvider\...ServiceProvider to config/app.php. Check the src/ namespaces after install — the README's class names are your source of truth.
Publish the config (tag name varies by version — run php artisan vendor:publish and pick the package entry):
```
php artisan vendor:publish --provider="Amin3536\\...\\ServiceProvider"
```

Register the package's custom driver in config/auth.php. The provider likely registers itself under a key such as api or api-user-provider (grep the service provider for Auth::provider( to confirm):

'providers' => [
    'users' => [
        'driver'   => 'api',
        'endpoint' => env('AUTH_API_URL'),
    ],
],
'guards' => [
    'web' => [
        'driver'   => 'session',
        'provider' => 'users',
    ],
],

First use case to validate the setup: a central identity service. Your web guard stays session-based, but Auth::attempt([...]) and Auth::user() resolve against the remote API instead of users table. Confirm with:
```
Auth::guard('web')->getProvider(); // should print the package provider class
Auth::attempt(['email' => '[email protected]', 'password' => 'secret']);
```

Before committing, verify Laravel version constraints in the package's composer.json. The current tag is v1.0.9, but its only change is a Guzzle dependency bump — feature code is still 2022-era, so expect Illuminate 9 support and treat 10/11 as untested. The upside: the bump should pull you onto a Guzzle 7 line that works cleanly on PHP 8.1+, which is a prerequisite for running this on modern Laravel at all.

Implementation Patterns

Central auth/identity provider (the intended pattern). Keep your local services' users tables empty or minimal and let the API provider own identity. All services share one AUTH_API_URL contract; sessions stay local per service. This is the lowest-friction integration and the reason the package exists.

API-only guard alongside a local guard. Register two providers and pick per guard — e.g., admin uses the api provider, customer stays Eloquent. This lets you migrate incrementally rather than moving every user at once:

'guards' => [
    'admin'   => ['driver' => 'session', 'provider' => 'api_users'],
    'web'     => ['driver' => 'session', 'provider' => 'users'],
],

Custom Authenticatable model. The package almost certainly returns a generic user object. Wrap or map it to your own App\Models\User implementing Illuminate\Contracts\Auth\Authenticatable so Auth::user()->id, is(), policies, and auth()->login() behave normally. If the provider returns raw arrays, a decorator implementing Authenticatable is worth writing before anything else — it's the seam every other pattern depends on.

Cache remote lookups. With the session driver, retrieveById fires on every request. Put a cache in front of the provider. The cleanest way is to decorate it rather than patch the package:

// AppServiceProvider::boot()
Auth::provider('cached-api', function ($app, array $config) {
    return new CachedUserProvider(
        $app->make(ApiUserProvider::class, ['config' => $config])
    );
});

Then use cached-api in config/auth.php. Invalidate the cache on updateRememberToken and on login/logout events.

Sanctum/Passport for service-to-service. The package authenticates users; it does not issue API tokens. Pair it with Sanctum: use the api provider for the human-facing session guard, and let viaRequest or Sanctum handle machine clients. Don't try to shoehorn both onto one provider.

Credential filtering. retrieveByCredentials in typical implementations forwards the whole credentials array to your API. Add a wrapper that whitelists fields so remember, CSRF sentinels, or guard-specific keys don't leak to the identity service.

Configure Guzzle, not just the config file. v1.0.9 confirms the transport is Guzzle. If the published config doesn't expose a timeout, bind your own client or GuzzleHttp\ClientInterface in a service provider and inject it — or register a Guzzle middleware that sets connect_timeout/timeout on the outgoing request. Doing it at the Guzzle layer survives package updates, whereas hand-editing src/ does not.

Gotchas and Tips

Unmaintained and effectively zero community. 11 stars, no dependents, and the most recent tag (v1.0.9) is a dependency bump, not a fix. Treat it as a reference implementation you may need to vendor/fork rather than a dependency. Read the UserProvider implementation line by line before shipping — it's small enough.
remember_me is likely a stub. Check whether retrieveByToken / updateRememberToken are implemented or no-ops. If updateRememberToken throws or no-ops silently, the "remember me" checkbox will misbehave in confusing ways (session cookie created, but no persistent token). Test explicitly.
Network failures masquerade as bad credentials. A timeout against the identity service typically bubbles up as null from retrieveByCredentials, so Laravel shows the same "These credentials do not match our records" message as a wrong password. Wrap the HTTP call and log failures separately — otherwise you'll chase phantom auth bugs during outages.
Missing timeouts and retries. A Guzzle version bump does not add retry logic. Set an explicit timeout and retry policy yourself — via the published config if it exposes one, otherwise via Guzzle middleware or a bound client. The default zero-timeout behavior on a slow identity service is a per-request hang under the session guard.
Version constraints can pin you to old Guzzle. Since the release only touched the Guzzle requirement, run composer why-not guzzlehttp/guzzle 7.x after install. If your app or another package already forces a specific Guzzle line, Composer may silently resolve to the older one this package still allows, which can reintroduce PHP 8.1+ deprecation noise.
Password rehashing is not supported. Laravel's EloquentUserProvider calls rehashPasswordIfRequired; this provider typically doesn't. That's fine if the identity service owns hashing — just be aware that changing HASH_DRIVER locally has no effect.
Debugging tip. Confirm the provider is wired before touching config:
```
dd(Auth::guard('web')->getProvider());
```
If you see Illuminate\Auth\EloquentUserProvider, your config/auth.php driver key is wrong or the service provider isn't registered. Clear a stale config cache with php artisan config:clear.
Extension points. The two useful ones are (a) registering the same or an alias driver with Auth::provider() in your own AppServiceProvider, and (b) implementing UserProvider yourself if you need caching, error handling, and credential whitelisting in one place — the interface is five methods and, given the abandonment risk, a ~100-line in-house provider is often the better bet.
Guard ordering matters. If you register a viaRequest callback and a custom provider on the same guard, viaRequest runs first; make sure you don't accidentally bypass the API provider you just configured.

Laravel Api User Provider Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips