When a Lumen developer first runs into authentication, the usual move — besides feeding keywords to Google — is to open the official Authentication docs. And then, like me, you go in hopeful and come out lost. If you reached Lumen without any Laravel background, that page leaves out so much that there’s nothing to hold onto.
Before I walk through the whole authentication setup in detail, let me first explain, roughly, what that short one-page Authentication doc is actually saying.
Authentication Service Provider
These days DI (Dependency Injection) is everywhere, so registering a service before you use it is second nature for most PHP developers. But most people register the AuthServiceProvider by the book, read the next paragraph, and stall. Where did this vague-looking block of code even come from?
$this->app['auth']->viaRequest('api', function ($request) {
// Return User or null...
});Every word looks familiar, and yet it doesn’t quite add up. Yes, we know it sits in the AuthServiceProvider’s boot method and runs when the service boots — but what is it actually doing?
Hold on — don’t rush. Let’s step back and set the big question aside for a moment. In plain terms, the flow that the whole official Authentication doc describes goes roughly like this:
- Register an authentication service in the system.
- When the service boots, set up a gatekeeper that checks incoming requests.
- During that check, if you need to identify the user, you can return a user object.
- In the auth middleware, call that gatekeeper to run the identity check.
For now I’ll answer the common questions in a quick Q&A. The full details and flow can wait for later posts.
Authentication Docs Q&A
Where does the viaRequest function come from? Does it mean “check the request”?
Yes and no. Going by the code comments, viaRequest reads less like via Request and more like via RequestGuard — it handles the request through a RequestGuard. When you call viaRequest, it registers a function that builds a RequestGuard. The actual RequestGuard object isn’t created until the first time that guard is resolved (more on that in a later post).
What is the api in viaRequest('api', …)?
This api isn’t directly tied to the API you’re building. It’s the key for a custom auth driver. You could swap it for any string in principle — just remember to make the matching change in config/auth.php.
What is the callback in viaRequest(…, callback)?
Here the callback is the function used to return a user object. In the docs’ setup, that returned user object does two things:
- It lets the RequestGuard decide whether the incoming request resolves to a user or a guest (returning null counts as a guest).
- When you call
$request->user(), this function runs to fetch the user object.
And where does app['auth'] come from?
As you’d expect, $this->app inside a ServiceProvider is the Lumen Application object itself, and app['auth'] is an AuthManager object that’s created automatically on access. Unless you touched app['auth'] earlier, this is most likely where it’s built for the first time — you can check by putting isset($this->app['auth']) before and after this block.
So what does the whole line $this->app['auth']->viaRequest('api', callback) mean?
In short: when the AuthServiceProvider boots, it uses the auto-created AuthManager to register a RequestGuard auth driver, then hands it a callback whose job is to decide on and fetch the user object.
Where’s the code that actually does the authentication?
In the docs’ setup there are two places. The first is inside the handle function of the Authenticate Middleware:
if ($this->auth->guard($guard)->guest()) {
return response('Unauthorized.', 401);
}Here it calls the Guard (the default api guard) to check whether the request is a guest. If it is, it denies access.
The second is inside the boot method of the AuthServiceProvider:
$this->app['auth']->viaRequest('api', function ($request) {
// Return User or null...
});If the user-object callback here returns null, then guard($guard)->guest() is true — the request is treated as a guest and access is denied. Return a user instead, and the request goes through.
Wrapping up
If this helped the official Authentication docs finally click for you, that genuinely makes my day. And if it didn’t — that’s okay. In the posts ahead I’ll take the whole authentication mechanism apart, as thoroughly as I can, and hopefully give you a new way to look at it by then.
