Cache Process Bundle Laravel Package

Technical Evaluation

Architecture Fit The cache-process-bundle remains a strong fit for Laravel/PHP applications that need process execution coupled with caching, built on Symfony Process and Symfony Cache. v2.2 deepens that fit by moving validation and policy into the task layer rather than the DI/config layer:

• adapter, key and value are no longer required in the bundle configuration (no placeholders needed); they are resolved once the task input is merged. This makes the Symfony service/DI graph cleaner and supports dynamic, per-invocation cache targets.
• A new AbstractCacheTask::getRequiredOptions() extension point formalizes how custom tasks declare mandatory options, which is the right seam for teams writing their own tasks on top of the bundle.
• GetTask gains an on_miss policy (output_null default, skip to route the input to error outputs, fail), giving explicit, configurable cache-miss semantics instead of implicit behavior.
• SetTask gains expires_after for per-item TTL, closing a real gap for cache hygiene.
• Diagnostics improved: duplicate adapter codes now report both service IDs (AdapterRegistry::addAdapter() accepts an optional $serviceId), and non-array task input now raises an explicit \UnexpectedValueException instead of a \TypeError from array_merge().

Integration Feasibility High, and higher than at v2.0. v2.2 is a minor release: no removals, no renames, no config schema breakage. The changes are additive (two new options, one new abstract method with a default-driven contract) plus behavior fixes. Existing v2.x integrations should upgrade with a composer update and no code changes, unless they:

• relied on passing loosely-typed option values through task input (those are now run through the options resolver and will be rejected if invalid), or
• relied on invalid cache keys being silently accepted — the documentation fix in #28 clarifies that Symfony adapters only reject invalid keys when assert() is enabled.

The relaxed configuration requirement is a genuine simplification, but it shifts validation from boot time to runtime, which must be understood before adoption.

Technical Risk

• Low Risk — Upgrade from v2.0/v2.1: Additive options, improved exceptions, expanded test coverage (GetTask, SetTask, option validation, context, missing adapter, stored null, overwrite, custom AbstractCacheTask subclasses, Adapter, bundle, DI extension). The obsolete test.old directory was removed, which is internal housekeeping.
• Low–Medium Risk — Deferred configuration validation: Because adapter, key and value are no longer required at configuration level, a missing or wrong value fails at task execution, not at container build. Misconfiguration surfaces in production paths rather than in CI.
• Medium Risk — Cache-key validation depends on assertions: With zend.assertions=-1 (typical production), Symfony adapters do not reject invalid keys. The bundle validates keys itself, but any key constructed outside the task path can still reach an adapter unvalidated. This is now documented rather than silently assumed.
• Medium Risk — Behavior fix surface: Input option values are now validated via the options resolver, and non-array input now throws \UnexpectedValueException. Both are correct behaviors that can break code which "worked" by accident. Any catch (\TypeError) blocks around task execution must be widened.
• Unchanged — Dependency Risk: Version alignment with symfony/process and symfony/cache remains the dominant integration hazard.
• New — Error-path design coupling: on_miss: skip routes input to the task's error outputs. That is a pipeline-topology decision, not a config tweak; it must be reviewed wherever downstream tasks assume a value on the success output.

Key Questions

1. Compatibility
   • Is the application on v2.0/v2.1 already, or jumping from v1.x directly to v2.2 (which compounds the v2.0 PHP/Symfony floor with these behavior fixes)?
   • Are there catch (\TypeError) blocks or type-tolerant wrappers around GetTask/SetTask that will no longer trigger?
   • Does any configuration currently pass option values as strings/loose types that the options resolver will now reject?
2. Functional Impact
   • What cache-miss behavior is correct per task: output_null, skip, or fail? The v2.2 default remains output_null, so unchanged configs silently keep prior semantics — confirm that is intended.
   • Which cache entries need an explicit expires_after, and what is the TTL policy per adapter?
   • Are cache keys constructed anywhere outside the task (custom services, jobs, Artisan commands) where assertion-based validation would not apply?
3. Testing
   • Do integration tests cover the new miss policies and TTL expiry against the real backend (Redis, Memcached, DynamoDB)?
   • Is there a test asserting \UnexpectedValueException on non-array input, and one asserting invalid-key rejection with assertions enabled in CI?
   • Has concurrency been exercised for on_miss: fail under partial cache outage?

Integration Approach

Stack Fit

• Target Stack: Laravel 10+, Symfony 8+, PHP 8.5 (unchanged from v2.0 baseline; v2.2 adds no new platform requirements).
• Legacy Stack: Laravel 9.x / Symfony 7.4+ with PHP 8.2+ after migrating off PHP 8.1.
• Non-Target: PHP 8.1 / Symfony 7.3 without migration.

Migration Path

1. Dependency Update
   • composer update cleverage/cache-process-bundle --with-dependencies to land v2.2.
   • No composer.json constraint change needed beyond an existing ^2.0 requirement; pin ^2.2 if you intend to depend on on_miss, expires_after, or getRequiredOptions().
2. Configuration Simplification
   • Remove now-unnecessary adapter / key / value placeholders from task definitions in the bundle configuration; supply them through task input instead.
   • If you maintain custom tasks, review whether they should override AbstractCacheTask::getRequiredOptions() rather than validating in execute().
3. Behavior Review
   • Decide on_miss per GetTask: keep the output_null default for tolerant pipelines, use skip where downstream tasks must not run on a miss, use fail for hard dependencies.
   • Add expires_after to SetTask definitions with an explicit TTL per data class.
   • Widen exception handling to catch \UnexpectedValueException (and keep \TypeError handling for defense in depth).
   • Audit duplicate adapter codes: the improved error message may reveal a previously tolerated registration collision.
4. Testing
   • Cover miss policies, TTL expiry, null-value storage/retrieval, and overwrite semantics.
   • Run the suite with zend.assertions=1 in CI to exercise adapter key validation, and separately with assertions disabled to confirm the application's own key validation holds.

Compatibility

• Symfony Components: symfony/process and symfony/cache must align with the v2 baseline (8.0+ on the target stack); the adapter layer is where key-validation behavior differs, so confirm the adapter in use.
• Laravel Services: No new conflicts with Artisan, queues, or Laravel's own process handling; verify task error-output routing does not collide with existing queue failure/retry semantics.
• PHP Extensions: pcntl / posix requirements unchanged.

Sequencing

1. CI First: Enable assertions in the test job and add cases for the new options before touching staging.
2. Staging Validation: Exercise on_miss variants and expires_after against the production-like cache backend.
3. Progressive Rollout: Ship with the output_null default (behavior-preserving), then opt individual tasks into skip/fail behind feature flags.
4. Rollback Plan: Revert the composer lock to the prior v2.x tag; configuration changes (removed placeholders, added options) should be kept additive so rollback does not require a config revert.

Operational Impact

Maintenance

• Pros: Broader automated coverage in v2.2 (tasks, options validation, adapter registry, DI extension) lowers regression risk on future upgrades. Config files are smaller without adapter/key/value placeholders. TTL support removes bespoke cache-expiry code.
• Cons: Validation now spans two layers (config for structure, runtime for adapter/key/value), which must be documented or on-call will look in the wrong place. Custom subclasses must adopt getRequiredOptions() to stay consistent.

Support

• Vendor Support: Actively maintained; v2.2 is largely a hardening and documentation release, and #28 corrected a misleading claim about key validation rather than shipping new behavior.
• Community: Symfony/Laravel-centric; cache-miss policy questions are answerable from the updated docs.
• Internal Support: On-call needs a clear mental model of on_miss semantics and the assertion-dependent key validation, since both change failure appearance without changing configuration.

Scaling

• Performance: expires_after enables TTL-based eviction, which bounds cache growth and is the main lever for memory pressure on Redis/Memcached clusters.
• Concurrency: on_miss: fail converts a cache outage into immediate task errors — good for latency, but it removes the implicit load-shedding that output_null provides and can stampede the origin. Test under load before adopting broadly.
• Resource Usage: on_miss: skip short-circuits downstream work on misses, reducing process spawns; monitor error-output volume as a proxy for cache hit rate.

Failure Modes

Ramp-Up

• Developer Onboarding: Document the three miss policies with concrete use cases, the TTL convention for expires_after, and the "config is optional, input is authoritative" rule for adapter/key/value.
• CI/CD Updates: Add an assertions-enabled test job; add task-execution smoke tests that would catch deferred configuration errors.
• Training: Cover getRequiredOptions() for anyone authoring custom tasks, and the assertion-dependent key validation so engineers do not rely on adapter-side rejection in production.