Taggable File Cache Laravel Package

Technical Evaluation

Architecture fit The package targets a real framework gap: Laravel’s native file cache store is not taggable, so Cache::tags([...]) is unavailable without Redis, Memcached, or the database store. torann/taggable-file-cache layers tag-index files over the local file cache and registers as a cache driver. Architecturally this is a narrow, replaceable component behind Laravel’s first-party Cache API, which is the right shape for a low-risk dependency: one store class, one driver registration, and a config entry. Call sites can stay framework-native, preserving an exit path to Redis later.

The temporal fit is poor. The last release is 1.0.0 from 2018-02-16, placing it in the Laravel 5.5/5.6 era. Laravel’s cache internals, package scaffolding, PHP minimums, config structure, and event wiring have changed since then. The likely outcome is that the package does not install cleanly against the current framework without a fork. The artefact worth evaluating is therefore the reference implementation, not the Composer dependency as-is.

Integration feasibility There are two credible paths, and the TPM should force an explicit choice:

1. Dependency path: composer require torann/taggable-file-cache, resolve illuminate/* conflicts, likely fork with widened constraints. This is fragile and should be pinned to an exact version or commit SHA.
2. Vendored source path: copy the store class into our codebase under BSD-2-Clause attribution, register a custom driver, and add internal tests. This is the credible path if we adopt the mechanism.

Either way, the integration surface is small — roughly one class, one driver registration, and configuration — on the order of days, not weeks. That is the key planning fact: this is a scoped cache-layer component decision, not a platform bet.

Technical risk

• Maintenance risk — very high: zero releases in roughly seven years, 2 stars, 0 dependents, single author, no visible issue history or fallback maintainer.
• Compatibility risk — high: version constraints and PHP floor are almost certainly incompatible with the current Laravel version. Porting effort is bounded but real.
• Correctness under concurrency — medium-high: tag-index files require locking discipline. Parallel writes and tag flushes can race, causing orphaned entries, stale cache, or premature invalidation. This must be tested, not assumed.
• Topology risk — disqualifying for most production fleets: file cache is node-local. A tag flush on node A does not invalidate node B. Under horizontal scaling, autoscaling, or containers this becomes a silent, user-visible correctness bug.
• Unbounded index growth — medium: tag index files accumulate without cleanup. Disk usage creeps unless a janitor process or cache-clear policy exists.
• Supply-chain risk — low to moderate: small, auditable codebase and permissive licence, but no security history in either direction.

Key questions

1. Which user-facing behaviour actually requires tag-based invalidation, and would key-versioning or namespace prefixes satisfy it more cheaply?
2. What is the deployment topology — single node, sticky routing, or horizontally scaled? This one answer decides viability.
3. Is adding Redis genuinely blocked by cost, ops, or compliance, or merely slower? Quantify in monthly spend and engineer-days.
4. Is the cheaper path to reimplement the tag-index pattern in-house rather than fork this package? The scopes are close; choose ownership deliberately.
5. Who is the named internal owner who can read and patch the source during a Laravel upgrade?
6. Does tag-index behaviour survive cache:clear, deploy-time cache wipes, file permission changes, and Octane worker lifetimes?
7. Are cached values small and regenerable, so a stale entry is a performance issue rather than a data-loss or entitlement issue?

Integration Approach

Stack fit The pattern fits any Laravel application. The package itself likely fits only older Laravel versions. Confirm with composer why-not torann/taggable-file-cache against the current lockfile before committing any estimate. Design call sites to use only Cache::tags([...]) and standard cache methods; do not leak package-specific APIs into application code.

Migration path There is nothing to migrate from, which removes the usual cutover risk, but there is also no upgrade guide, changelog, or test suite to lean on. The important migration property is the exit path: because consumers use Laravel’s standard taggable cache API, replacing this store with Redis later is a driver swap in config, not an application refactor. Preserve that property and the cost of being wrong stays low.

Compatibility We must author the support matrix ourselves: supported PHP versions, Laravel majors, single-node versus multi-node fleet, Octane worker lifetime, cache:clear semantics, deploy-time cache wipes, file permissions, and lock behaviour. Treat compatibility as an internal test obligation, not an upstream guarantee.

Sequencing

1. Timeboxed spike — 1–2 days: fork or vendor the source, widen constraints, install against our Laravel version, and prove Cache::tags([...])->flush() semantics end to end.
2. Concurrency test: run parallel writes plus a tag flush; assert no stale or orphaned entries survive.
3. Decision gate: single-node or sticky-routed deployment makes it a viable candidate; multi-node or autoscaling rejects it as a dependency and harvests the design as reference only.
4. Harden before adoption: vendor into our repository with BSD-2-Clause attribution, add internal tests, pin to a commit SHA rather than ^1.0, and document the removal path.
5. Feature-flagged staging soak: run for one release cycle behind a flag, with monitoring for stale content and cache growth.
6. Re-assessment trigger: any Laravel major upgrade or any change to deployment topology reopens the decision.

Operational Impact

Maintenance Plan on fork-and-vendor as the operating model, not on upstream support. Initial sizing is roughly 1–3 engineer-days to port and test, then about half a day per quarter to keep alive, with spikes on Laravel majors. Nominate a named owner on day one and record the component in the tech-debt register as internally owned.

Support There is no upstream support policy, security advisory history, or compatibility commitment. Internal support must cover incident triage, patching, and upgrade work. Provide a short runbook: where tag indexes live, how to flush safely, how to clear the cache directory, and how to verify tag invalidation after deployment. Avoid using this component for correctness-critical data such as entitlements, pricing, or permissions.

Scaling Acceptable only for single-node deployments or environments where all traffic is sticky to one node. For multi-server, autoscaled, or containerised deployments, reject it and use Redis, Laravel’s native taggable store. File cache also incurs disk I/O per read and per tag operation, so high-throughput workloads are a poor fit. Tag index growth and node-local invalidation are scaling constraints, not just performance concerns.

Failure modes

• Stale content across nodes: a tag flush on one node does not invalidate siblings; this is the highest-severity failure mode.
• Tag-index drift: orphaned keys or stale tag membership after races or interrupted flushes.
• Premature invalidation: concurrent flush and write operations can drop entries unexpectedly.
• Index bloat: tag index files accumulate without a cleanup policy.
• Deploy-time cache wipe: deployments that clear the cache directory may remove tag indexes or payloads inconsistently.
• Silent correctness failures: tag bookkeeping can fail without loud errors, so monitoring must include hit rate, cache-directory size, flush errors, and user reports of stale content.

Ramp-up Ramp-up is small for an engineer familiar with Laravel’s cache layer: the source is small enough to read, and the integration surface is one driver registration. Budget half a day to a day for orientation, plus the spike and concurrency test. The TPM should treat the ramp-up as an internal ownership exercise, not as learning a supported third-party product. If the team cannot name an owner and a removal path, do not adopt it.