Download the PHP package brynforum/api-cache without Composer

brynforum/api-cache

A Flarum extension that adds server-side response caching to the JSON:API. Configure regex-pattern rules with per-rule TTLs to short-circuit expensive endpoints — top-poster widgets, statistics aggregations, public discussion lists — before they touch the database.

Built and used in production by BrynForum.

Why

Flarum re-aggregates SQL on every request to certain API endpoints. The canonical example is /api/users?filter[top_poster]=true — the popular afrux/top-posters-widget hits it on every page load, and the answer changes once an hour, not once a request.

Edge-caching the response at Cloudflare is a workaround at the wrong layer (and on free/pro plans, Set-Cookie blocks caching anyway). The right fix is caching inside Flarum, where the rules can be tuned per-tenant in admin and the cache key can include exactly what matters.

Installation

Then enable API Cache under Admin → Extensions.

The extension creates a brynforum_api_cache_rules table on first enable.

Optional: Redis backend

The extension uses Flarum's default file cache out of the box. To use Redis (recommended for busy forums), set these environment variables on the container:

The extension auto-detects the env vars, pings the host, and uses Redis if reachable — otherwise transparently falls back to the file driver. Check the active backend via the X-BrynForum-Cache-Backend: redis|file response header.

PHP-FPM defaults to clear_env = yes on most distros. Set clear_env = no in your php-fpm.conf so PHP can read the env vars at runtime.

How it works

A PSR-15 middleware sits on Flarum's API stack. For each GET request:

1. Walks active rules in priority order; checks the path against path_pattern (PCRE regex) and the querystring against query_filter (optional regex). First match wins.
2. Computes a stable cache key: sha1(method + path + sorted(query) + scope).
3. On HIT: returns the cached 200 response (with original headers minus Set-Cookie). No handler invocation, no DB queries.
4. On MISS: runs the handler. If the response is 200, caches it with the rule's TTL.

Configuration

Admin → API Cache. Add rules with:

There's a Clear all cache button to invalidate everything in one click.

Scopes

• public — cache shared across all visitors. Use for endpoints whose response doesn't depend on identity (top-poster lists, public stats, discussion index when no per-user filter applies).
• guest — cache used only when the request has no session. Authenticated users bypass the cache entirely, so their identity-specific responses never land in a shared bucket.

Verifying it works

Every matched response goes out with two debug headers:

• X-BrynForum-Cache — one of:
  • HIT — served from cache, handler never ran.
  • MISS — handler ran, response stored.
  • SKIP-status — handler ran, response not stored (non-200).
  • SKIP-private — handler ran, response not stored (handler returned Cache-Control: private or no-store).
  • SKIP-authseed — handler ran for an authenticated request, response not stored because the rule disallows authenticated seeding (other auth users get fresh handler responses; only guest requests warm this cache).
• X-BrynForum-Cache-Backend: redis | file — which backend is active.

Example:

Safety properties

The extension enforces these regardless of how rules are configured:

• Only 200 OK responses are cached. Errors, 4xx and 5xx pass through untouched.
• Only GET requests are eligible. Non-GET passes through.
• Set-Cookie is stripped from cached responses (avoids session leakage).
• The cache key does not include Authorization headers or session cookies — only path + querystring + scope. This is intentional: public scope means "same for everyone"; guest scope means "only used when unauthenticated".
• Rule list itself is cached for 60 s and explicitly invalidated when rules change, so admin edits take effect quickly.
• Cache-Control: private and Cache-Control: no-store are honoured. If the route handler explicitly marks a response per-user (Flarum or any extension), it's never cached even if the rule says scope=public. The response goes out with X-BrynForum-Cache: SKIP-private.
• The rule validator refuses scope=public for known per-user paths — patterns matching /api/users/<id>, /api/users/me, /api/notifications, /api/preferences, /api/access_tokens. Operator gets a clear error pointing them at scope=guest.
• Per-rule "guest-only seed" mode. Each rule has an Allow authenticated requests to seed cache flag. When off, authenticated requests bypass the write path (their response is returned but not stored); everyone still reads from cache when it's warm. Closes the "admin's response, with email included, lands in a shared bucket guests subsequently read" hole on endpoints like /api/users?filter[top_poster]=true. Surfaces as X-BrynForum-Cache: SKIP-authseed when an auth request would have seeded but didn't.

When NOT to cache

Some endpoints respond differently to different users even at the same URL. Caching them at scope=public will leak one user's data to another. Use scope=guest (or don't cache at all) for:

Safe at scope=public:

If you're unsure, set the rule to scope=guest first and verify the response shape is identical to what a logged-out visitor sees. Promote to scope=public only once you're certain there's no per-user variation.

Example rules

Contributing

Issues and PRs welcome. The extension is intentionally small and focused; before opening a large PR, please file an issue to discuss.

License

MIT © BrynForum