What to Uncomment in Lumen's bootstrap/app.php (and What It Costs You)

You picked Lumen for a small JSON API because it's fast and lean. Then you open bootstrap/app.php and find the two lines that decide what kind of framework you actually got: $app->withFacades(); and $app->withEloquent();, both commented out. Enable them and you've rebuilt a good chunk of Laravel. Leave them off and you're writing a micro-framework app with unfamiliar ergonomics. This is the real Lumen decision, and it's worth making deliberately.

What Lumen actually ships with

Lumen is Laravel with the conveniences stripped: same service container, same router style, same Eloquent ORM available, but most of it dormant. Out of the box you get routing, middleware, dependency injection, and .env-based configuration loaded directly in the bootstrap file. What you don't get by default: facades (the static-style DB:: or Cache:: calls), the database layer, and several artisan commands Laravel developers take for granted — notably, depending on version, route:cache and config:cache.

That last point matters operationally. If your deployment script assumes cached config and routes, test it against your Lumen version before go-live; you may find those commands missing and need to rely on OPcache plus a fast bootstrap instead.

The two switches and their trade-offs

$app->withEloquent() boots the database component and Eloquent. For almost any real API you want this — hand-rolling queries without it saves little and costs a lot of clarity. $app->withFacades() registers facade aliases so Laravel-style code and many packages work unchanged. Both add bootstrap work to every request, which is precisely the overhead Lumen exists to avoid.

The honest position: if you enable facades, Eloquent, and a pile of Laravel packages, you've narrowed the performance gap that justified Lumen in the first place. That's fine if you chose Lumen for its smaller surface area and API focus rather than raw throughput. But if throughput was the motivation, measure. Run a simple wrk or ab benchmark against one endpoint with the switches on and off:

# Run from any machine that can reach the app; no special permissions needed
wrk -t2 -c20 -d15s http://localhost:8000/users

Compare requests-per-second between configurations. On a small API the difference is often modest once OPcache is enabled, but "often" is not a number — get your own.

A worked example: paginated users endpoint

With Eloquent enabled, pagination behaves exactly as in Laravel. In routes/web.php (yes, Lumen keeps the name even for APIs):

$router->get('/users', function () {
    return \App\Models\User::paginate(15);
});

A request to GET /users?page=2 returns a JSON envelope containing data, current_page, last_page, per_page, and total — no transformer required. Verify it with:

curl -s "http://localhost:8000/users?page=2" | php -r '
  $r = json_decode(stream_get_contents(STDIN), true);
  foreach (["data","current_page","last_page"] as $k) {
    echo $k, ": ", array_key_exists($k, $r) ? "present" : "MISSING", PHP_EOL;
  }'

If your dataset is large and you don't need a total count, simplePaginate(15) skips the COUNT(*) query and returns a leaner envelope — a cheap win on big tables.

Authentication and packages: where Lumen bites

Lumen targets stateless APIs, so session and view tooling is minimal. Authentication is typically token-based: clients send an Authorization header, and guards in config/auth.php resolve the user per request. If you find yourself wanting cookie sessions, login forms, or CSRF middleware, that's a signal you wanted Laravel.

The same applies to packages. Many Laravel packages assume services Lumen doesn't register — session, view, config caching. Before adding a package, check its service provider for references to those services, or just install it in a throwaway branch and hit one endpoint. A fatal error on boot is a fast answer.

One more caution for 2026: Lumen's release cadence has historically lagged Laravel's. Before committing, check composer.json and the versions under vendor/laravel/ to confirm your Lumen release aligns with a Laravel component set that still receives security fixes, and that your PHP version is supported by both.

A practical default

For a small stateless JSON API, a defensible starting configuration is: Eloquent on, facades on (the ergonomics are worth it once Eloquent is already booted), token auth, PHP-FPM behind Nginx with OPcache enabled. Then benchmark one hot endpoint and decide whether anything needs to come back out. The framework's whole pitch is that you pay only for what you enable — but that only holds if you actually check the bill.