Cache Laravel Package

Getting Started

This package is a read-only split of the marko-php/marko monorepo; it ships the cache contracts and infrastructure, not a standalone application dependency. In practice you almost never composer require marko/cache directly — it arrives transitively when you install the framework or a component that needs caching. If you do need it in isolation (e.g., building a custom integration), add it and pull the implementation package your driver needs.

Where to look first, in order:

1. src/ — find the primary contract (typically CacheInterface) and the CacheManager/factory that resolves drivers. Read the interface signatures before anything else; they define the whole surface you'll code against.
2. The driver implementations (array, file, and any Redis/Memcached adapters). The array driver is your mental model for testing; the file driver is your default for local dev.
3. Config/binding layer — see how the manager is registered in the service container and how driver configuration is read. This tells you how to swap drivers per environment.
4. The test suite — it's the fastest way to see intended usage for get/set/delete/remember semantics.

First use case: wrap an expensive read (a DB aggregate, a third-party API call, a rendered fragment) so subsequent requests hit the cache. Something like resolving the cache from the container, checking for a key, and falling back to the source on a miss.

Implementation Patterns

Cache-aside with remember. The dominant pattern. Prefer the remember($key, $ttl, $callback) style so the check-compute-store sequence lives in one place and the miss path is exercised the same way every time. Use rememberForever sparingly — prefer an explicit TTL even if it's long.

Inject the contract, not the manager. Type-hint CacheInterface in constructors and let the container wire the configured driver. Reserve the CacheManager for code that genuinely needs to select a driver at runtime (multi-store setups, admin tooling).

Namespacing keys deliberately. Build keys with a prefix per domain — user:{id}:profile, report:{hash}:v3. Version tokens in the key (the v3 above) are a cheap, driver-agnostic invalidation strategy and often preferable to tags when drivers differ across environments.

Tags for group invalidation. Where the driver supports tags, use them for "invalidate everything tied to this entity" flows (e.g., flush a customer's cached views on update). Isolate the calls behind a small repository/service wrapper so a tag-less driver doesn't leak into call sites.

Decorator pattern for repositories. Wrap a repository in a CachedUserRepository that delegates to the real one on miss. This keeps cache concerns out of the data layer and makes it easy to disable caching in tests by injecting a passthrough decorator.

Fragment caching in the view layer. For rendered partials, cache the rendered string keyed by the data that feeds it, not the whole page. This gives you granular invalidation and avoids blowing away an entire layout for a single stale component.

Testing switch. Bind the array driver in your test container so each test gets a clean, in-memory store. If your tests assert "no cache hit," make the array store explicit rather than relying on a null driver.

Gotchas and Tips

• Read-only repo. Any fix or feature goes through the main marko-php/marko monorepo. Don't open PRs here, and don't vendor-patch — you'll lose the change on the next split. If this package is a blocker, that's a strong reason to file upstream.
• Stars/ecosystem signal is thin. Zero dependents and zero stars on this split means the docs and examples you'll find are essentially the interface definitions themselves. Budget time to read source and tests rather than searching for tutorials.
• TTL units. Confirm whether TTLs are seconds (the common convention) or DateInterval/DateTimeInterface. Mixing the two silently produces caches that never expire or expire immediately. Check the driver's test for the authoritative behavior.
• Serialization assumptions. Most cache backends serialize values. Closure-bearing objects, resources, and some ORM entities won't round-trip cleanly. Cache plain arrays/scalars/DTOs, and re-hydrate models from IDs.
• Cache stampede / negative caching. A popular key expiring under load will hammer your source. Consider a short "lock" or "soft TTL" pattern, and decide explicitly whether to cache null/false results (recommendation: cache them with a short TTL to avoid penning repeated misses).
• Driver portability. Tags, increment/decrement, and TTL precision vary by driver. If you rely on any of these, write a smoke test and run it against every driver you deploy.
• Config caching footgun. If the framework caches config, editing cache config locally won't take effect until you clear the config cache. This trips people up when debugging "why isn't my driver switching?"
• Extension points. The manager and the interface are the seams: a custom driver implementing CacheInterface is the sanctioned way to add a backend, and a decorated cache is the sanctioned way to add cross-cutting behavior (logging, metrics, key prefixing) without touching call sites.
• Debugging misses. If you're not sure whether a miss is a driver issue or a key/TTL issue, drop in a logging decorator around CacheInterface — it's a five-minute change and beats sprinkling var_dump in your services.