Laravel Firebase App Check Laravel Package

Getting Started

• Install with composer require the package, then publish its config: php artisan vendor:publish --tag=... (check vendor/ for the exact tag). The config file is your first stop — it holds the projects map that everything else keys off.
• Define at least one project in config with a name, its Firebase project ID, and credentials. Credentials can be a key-file path, a JSON string, or a plain array — prefer a path (or a secret-mounted file) in production and never commit the JSON.
• Register the middleware alias firebase-app-check in bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php (Laravel 10). Add it to your API group, before auth:sanctum, so unverified clients never reach your auth or DB layer.
• First use case: protect a mobile-facing API. The client calls FirebaseAppCheck.getToken() and sends X-Firebase-AppCheck: <token> on every request; your routes are hard-enforced by default, GET reads fall back to soft enforcement automatically.
• Verify it works by hitting a protected route with no header (expect rejection) and with a valid token (expect success), then use AppCheck::fake() in a feature test to pin the behaviour down.

Implementation Patterns

• Global middleware + per-route opt-out. Put firebase-app-check on the whole API group and relax individual routes with firebase-app-check:soft — useful for endpoints your web app also calls (read-heavy public catalogues, health pings).
• Soft mode is a rollout tool, not a resting state. Reads and :soft routes still reject unknown/unconfigured projects, so soft mode only loosens token verdicts. Use it while instrumenting clients, then flip to hard.
• Multi-project / multi-tenant setups. Key projects by name and use aliases so a tenant or app flavour resolves to a distinct Firebase project. Where the project is derived from the request (subdomain, header, JWT claim), implement AppCheck::resolveProjectUsing(fn ($request) => ...) in a service provider rather than duplicating config lookups in middleware.
• Dynamic opt-out. AppCheck::skipWhen(fn ($request) => ...) handles webhooks, CORS preflight, health checks and internal service calls without sprinkling :soft across route files.
• Consistent error contract. AppCheck::rejectUsing(fn ($request, $reason) => response()->json([...], 401)) gives you one response shape for mobile clients instead of the default. Pair it with reportUsing() to route failures into your logging/alerting channel so you can see rejection rates per project before enforcing hard.
• Manual verification with AppCheck::verify($token, $project = null) when the token arrives somewhere middleware can't see it — queue jobs, websocket handshakes, an upload endpoint accepting a signed URL request.
• ID-token sign-in. Use IdTokenVerifier in your login/registration controller: verify the Firebase ID token, get an Identity back, then either Auth::login() a local user or mint a Sanctum/Passport token. Keep the exchange in one action/controller so both mobile and web sign-in paths share it.
• Testing. AppCheck::fake() and IdTokenVerifier::fake() in setUp(); then assertVerified() / recorded-verification assertions in each test. This removes network calls from CI and lets you assert which project and token were checked — a real gap when you support several projects.

Gotchas and Tips

• Unknown project names fail even in soft mode. A typo in a project name or alias, or a request that resolves to no project, is a hard reject regardless of :soft. If reads start failing after a config change, check project resolution first, not the token.
• Header stripping. X-Firebase-AppCheck is custom, so CDNs, load balancers, some proxies and serverless gateways may not forward it. Verify with a raw request before blaming the package.
• The verdict cache is short by design — bounded by the token's own expiry. Don't build on it for rate limiting or "verified once per session" logic.
• Outages are never cached, so a Firebase/Google outage means every request retries verification. Add your own circuit breaker or a short timeout if your traffic profile makes this a thundering-herd risk.
• Distinguish InvalidIdToken from IdTokenVerificationFailed. The first is the client's problem (401, "sign in again"); the second is infrastructure (503/retry, alert). Collapsing both into a 401 will mask outages as auth failures and confuse users.
• Clock skew on token expiry. Keep the host's clock in sync (NTP) and expect near-expiry tokens to fail; clients should refresh proactively rather than on 401 only.
• Credentials as env JSON strings are fragile across multiline/quoting and some hosting UIs. Prefer a mounted key file, or base64 the JSON in env and decode it in config.
• Fakes are per-test. Re-apply them after any RefreshDatabase/container rebinding in unusual setups, and remember a fake that was never consulted passes silently — assert on recorded verifications rather than just the response status.
• Pre-1.0 surface area. At 0.1.0, treat facade signatures, config keys and exception hierarchies as unstable; pin the version and read the changelog before minor bumps.