Facades
In Laravel, a facade is a class with static methods, like Cache::get('key') or Log::info('hi'), that quietly forwards each call to a real service inside the app’s container. It reads like a global, but behind it is an object you can swap.
Strutvane’s version is planned for 0.2: typed static accessors with Laravel’s short names (Log, Cache, DB, Route, Mail, Storage, Http, Queue, Event, Bus, Notification, Hash, Crypt, Url), resolved from the current app’s container, with no magic and with fakes for tests. This page explains how they’ll work, and what to use today.
The smallest example (preview)
Section titled “The smallest example (preview)”import { Controller, Log, type HttpContext } from '@strutvane/framework'
export class ReportController extends Controller { async show(ctx: HttpContext): Promise<Response> { Log.info('Report opened', { report: ctx.param('report') }) return ctx.json({ data: { opened: true } }) }}What you’ll see in storage/logs/strutvane.log (something like this; request id and user are added for you):
[2026-11-15 10:00:00] local.INFO: Report opened {"report":"monthly","requestId":"01J…","userId":1}Why “static” doesn’t mean “global” here
Section titled “Why “static” doesn’t mean “global” here”A Laravel facade asks one global container. Strutvane’s accessors ask the current app, the same way config() and route() do: Strutvane remembers which app is handling the request (with Node’s AsyncLocalStorage) and the accessor looks up its service in that app’s container.
Log.info('hi') └─► current app (this request's app) └─► container.make(LoggerToken) └─► the logger you (or a test) boundSo:
- swapping works per app: bind a different logger in one test’s app and only that test sees it;
- outside a request an accessor fails with the same friendly “called outside a request or console command” error as the helpers, telling you to use
app.run(); - nothing is hidden: each accessor is a thin, typed shortcut to one container token, listed below.
The planned accessors
Section titled “The planned accessors”| Accessor | Shortcut to | Laravel | Fake for tests | Arrives with |
|---|---|---|---|---|
Log |
the logger (LoggerToken) |
Log:: |
capture lines in memory | 0.2 (Logging) |
Cache |
the cache store | Cache:: |
an in-memory store | 0.3 (Cache) |
DB |
the database connection | DB:: |
— (tests use a real test database) | 0.2 (Database) |
Route |
the route builder | Route:: |
— | already here (Routing) |
Mail |
the mailer | Mail:: |
Mail.fake(), then assert what was sent |
0.2 (Mail) |
Storage |
file disks | Storage:: |
Storage.fake(), a temporary disk |
0.2 / 0.3 (File Storage) |
Http |
the outgoing HTTP client | Http:: |
Http.fake(), Http.preventStrayRequests() |
0.2 (HTTP Client) |
Queue |
the queue | Queue:: |
Queue.fake() |
0.3 (Queues) |
Event |
the event dispatcher | Event:: |
Event.fake() |
0.2 (Events) |
Bus |
dispatching jobs and chains | Bus:: |
a fake that records dispatches | 0.3 (Queues) |
Notification |
notifications | Notification:: |
Notification.fake() |
0.3 (Notifications) |
Hash |
password hashing | Hash:: |
— | 0.2 (Hashing) |
Crypt |
encryption (encrypt() / decrypt()) |
Crypt:: |
— | 0.2 (Encryption) |
Url |
URL generation and signed links (url.signedRoute()) |
URL:: |
— | 0.2 (Routing) |
A row arrives together with the feature it fronts: Cache can’t exist before the cache does.
Every way to reach a service
Section titled “Every way to reach a service”The accessors are one of three ways to get a service. All three end at the same container binding, so they always agree.
1. Constructor injection (recommended for your classes)
Section titled “1. Constructor injection (recommended for your classes)”The class says what it needs; the container passes it in. Best for testing and for reading code, because dependencies are visible at the top of the class. This works today:
import { Controller, LoggerToken, type HttpContext, type Logger } from '@strutvane/framework'
export class StatsController extends Controller { static readonly inject = [LoggerToken] as const readonly #log: Logger
constructor(log: Logger) { super() this.#log = log }
show(ctx: HttpContext): Response { this.#log.info('Stats viewed') return ctx.json({ data: {} }) }}See Service Container.
2. Helpers and app() (anywhere, today)
Section titled “2. Helpers and app() (anywhere, today)”import { app, LoggerToken } from '@strutvane/framework'
app().container.make(LoggerToken).info('Hello')See Helpers.
3. Accessors (anywhere, coming in 0.2)
Section titled “3. Accessors (anywhere, coming in 0.2)”import { Log } from '@strutvane/framework'
Log.info('Hello')The shortest, for code that isn’t a class you control: a route closure, a small function, a seeder.
| Injection | app() |
Accessor | |
|---|---|---|---|
| Typed | yes | yes | yes |
| Dependencies visible | yes, in static inject |
no | no |
| Needs a class | yes | no | no |
| Works today | yes | yes | coming in 0.2 |
Faking in tests (preview)
Section titled “Faking in tests (preview)”Each accessor that talks to the outside world gets a fake that replaces the real service in that test’s app only:
import { randomBytes } from 'node:crypto'import { expect, test } from 'vitest'import { Mail } from '@strutvane/framework'import { client } from '@strutvane/framework/testing'import { createApp } from '../../bootstrap/app.ts'
test('signing up sends a welcome mail', async () => { const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, DB_CONNECTION: 'sqlite' }) await app.run(async () => { Mail.fake() await client(app).postJson('/register', { name: 'Asha', email: 'asha@example.test', password: 'a long password here' }) Mail.assertSent('WelcomeMail', (mail) => mail.to === 'asha@example.test') })})import { expect, test } from 'vitest'import { Http } from '@strutvane/framework'
test('rates are read from the partner', async () => { Http.preventStrayRequests() // any request without a fake fails the test Http.fake({ 'https://rates.example.com/*': { status: 200, body: { rate: 1.08 } } }) // … call your code, then assert on the result})What you’ll see: the tests pass without sending mail or calling the internet. With preventStrayRequests(), an un-faked request fails loudly instead of reaching a real server.
When to use which
Section titled “When to use which”- Your own classes (controllers, services, middleware): inject. It’s explicit and needs no current app.
- Route closures, seeders, small functions: accessors (or
app()until they arrive). - Library code you publish as a package: inject, and bind your defaults in your provider.
Common mistakes
Section titled “Common mistakes”“… was called outside a request or console command”
Section titled ““… was called outside a request or console command””✖ Log.info() was called outside a request or console command, so there is no current app.→ Call it from a controller, middleware or command, or wrap the code in app.run(() => …) (tests: await app.run(async () => …)).Why: accessors read the current app, which exists only while a request or command runs. (This preview reuses the helpers’ error, which exists today.)
Fix: call it inside a function that runs during a request, or wrap it: await app.run(async () => Log.info('hi')).
Route::get() from a Laravel tutorial doesn’t work
Section titled “Route::get() from a Laravel tutorial doesn’t work”Why: TypeScript uses a dot for static members, and Strutvane’s Route.get() returns a route value that you put in defineRoutes([...]). Calling it alone registers nothing.
Fix:
import { defineRoutes, Route } from '@strutvane/framework'
export default defineRoutes([ Route.get('/hello', (ctx) => ctx.json({ message: 'Hello!' })),])My fake leaked into another test
Section titled “My fake leaked into another test”Why: it can’t with Strutvane’s design (each fake belongs to one app), so the other test is probably using the same app object.
Fix: create a fresh app per test with createApp({ … }).
Cache.get() isn’t there
Section titled “Cache.get() isn’t there”Why: Cache arrives with the cache itself, in 0.3.
Fix: for now, keep cached values in a singleton() service, or wait for Cache.
Next steps
Section titled “Next steps”- Helpers: the functions that work today.
- Service Container: tokens, bindings and injection.
- Mocking: fakes in tests.
- Logging:
Logchannels and context.