6.4 Caching Strategy
KMP uses CakePHP cache configurations backed by the configured Redis or file engine. Application data may be tenant-scoped or intentionally platform-scoped; that distinction matters more than the engine.
Configured caches
| Configuration | Typical content | Current duration |
|---|---|---|
default |
General application values | 1 hour |
member_permissions |
Effective member authorization data | 30 minutes |
permissions_structure |
Role/permission relationships | 999 days, explicitly invalidated |
branch_structure |
Organizational hierarchy | 999 days, explicitly invalidated |
grid_filter_options |
Relatively static grid option lists | 10 minutes |
tenant_host_map |
Platform host-to-tenant lookup | Platform-managed configuration |
restore_status |
Shared restore lock/progress | Restore-specific configuration |
_cake_translations_ / _cake_model_ |
Framework metadata | Framework-managed |
Durations are defaults in app/config/app.php, not a substitute for invalidation when writes change security- or structure-sensitive data.
TenantAwareCache
New tenant-domain cache code should use TenantAwareCacheInterface. Its tenant keys are prefixed with both the sanitized tenant slug and ID:
t:<tenant-slug>:<tenant-id>:<application-key>
It provides read, write, add, delete, and remember. With no tenant context, the default service can preserve a single-tenant plain key; construct/configure strict mode for code where a missing tenant must fail. Worker and multi-tenant code should treat missing context as an error.
readPlatform(), writePlatform(), and deletePlatform() use a platform: prefix and are only for values intentionally shared across tenants. The host map is a platform concern. A tenant plugin must not use platform keys merely to avoid tenant-context setup.
Key and invalidation rules
- Use stable, non-sensitive identifiers; never include names, emails, tokens, or document contents in keys.
- Include all inputs that change the result, beyond the tenant prefix.
- Invalidate or update cache only after the database mutation commits.
- Clear permission/branch/grid caches through existing table/service hooks when their source records change.
- Do not cache mutable ORM entities for reuse across requests or tenant switches.
- Keep cache misses correct and reasonably bounded; the cache is not the source of truth.
Multi-replica behavior
Redis-backed caches share state across replicas; file caches do not. Restore status and any correctness-sensitive coordination must use their explicitly configured shared mechanism. Do not build locks or durable job state on the general cache.
Verification
Test hit/miss behavior, invalidation, global versus scoped permissions, tenant key collisions, missing-context strict mode, platform key isolation, serialization-safe values, and operation with both supported cache engines where the change depends on engine behavior.