Cache Process Bundle Laravel Package

Getting Started

Cache Process Bundle wires cache reads and writes directly into your Symfony Workflow as tasks. Instead of hand-rolling cache logic inside each workflow step, you compose GetTask and SetTask into your places/transitions and let the bundle handle options, adapters, and miss behaviour.

1. Installation:

   composer require cleverage/cache-process-bundle
   

2. Register the bundle in config/bundles.php (Symfony) and declare your cache adapters under cleverage_cache_process: in your bundle config. Adapters are collected by a compiler pass and keyed by code.
3. First use case — cache a value between two workflow steps:

   # config/packages/workflow.yaml
   framework:
       workflows:
           my_workflow:
               places: [start, cached, done]
               transitions:
                   fetch:
                       from: start
                       to: cached
                       metadata:
                           task: Cleverage\CacheProcessBundle\Task\GetTask
                           adapter: main
                           key: 'user_%userId%_profile'
                   store:
                       from: cached
                       to: done
                       metadata:
                           task: Cleverage\CacheProcessBundle\Task\SetTask
                           adapter: main
                           key: 'user_%userId%_profile'
                           expires_after: 3600
   

   Options (adapter, key, value) do not have to be set at configuration level — they can be supplied entirely by the workflow input and are merged at runtime.

Implementation Patterns

GetTask — reading from cache

GetTask reads key from the configured adapter. As of v2.2 you can control what happens on a miss with on_miss:

task: Cleverage\CacheProcessBundle\Task\GetTask
adapter: main
key: 'report_%reportId%'
on_miss: output_null   # default: emits null to the main output
# on_miss: skip        # sends the input to the error outputs
# on_miss: fail        # fails the task

Choose skip when a missing cache should trigger a fallback branch, and fail when a missing cache is unexpected. output_null keeps the workflow's happy path flowing with a null value.

SetTask — writing to cache

SetTask writes value to key on the configured adapter. Use the new expires_after option to set the per-item TTL:

task: Cleverage\CacheProcessBundle\Task\SetTask
adapter: main
key: 'report_%reportId%'
value: '@output.report'
expires_after: 86400   # store for one day

expires_after is optional — omit it to fall back to the adapter's default lifetime.

Config-time vs runtime options

Options no longer need placeholders at configuration time. You can:

• Declare adapter/key once in the workflow definition and rely on input values, or
• Omit them entirely and supply them from the workflow context. The task validates the merged options via Symfony's OptionsResolver, so invalid values surface as clear errors instead of silently flowing through (fixed in #23).

Custom cache tasks

Extend AbstractCacheTask to build your own caching tasks. Override getRequiredOptions() (new in v2.2) to declare which options must be present after merging:

use Cleverage\CacheProcessBundle\Task\AbstractCacheTask;

class PutTask extends AbstractCacheTask
{
    protected function getRequiredOptions(): array
    {
        return [...parent::getRequiredOptions(), 'key'];
    }
}

The bundle's tests cover custom tasks, options validation, context handling, null storage, and overwriting, so this extension point is well-exercised.

Custom adapters

Register adapters via configuration (compiler pass picks them up) or programmatically with AdapterRegistry::addAdapter(). Since v2.2 the registry accepts an optional $serviceId argument, so duplicate code collisions report both service IDs in the exception — invaluable in large bundles.

Gotchas and Tips

PHP/Symfony version compatibility

• v2.0+ requires PHP 8.5 and Symfony 8; PHP 8.1 and Symfony 7.3 are dropped.
• Align composer.json:

  "require": {
      "php": "^8.2 || ^8.3 || ^8.4 || ^8.5",
      "symfony/*": "^7.4 || ^8.0"
  }
  

Key validation is conditional (documentation fix #28)

Invalid cache keys are only rejected by Symfony adapters when assert() is enabled (zend.assertions=1 in development). In production the same bad key may silently flow through. Don't rely on assertions for user-facing key validation.

Non-array input now raises a clear error (#22)

Passing a scalar instead of an array to GetTask/SetTask used to trigger an opaque \TypeError from array_merge(). Since v2.2 it throws an explicit \UnexpectedValueException — catch or guard against this in custom workflow listeners.

Options are validated at runtime (#23)

Option values supplied by workflow input are now run through OptionsResolver. If you were relying on loose types (e.g. passing a string where an int TTL is expected) you may start seeing validation errors — cast early.

Duplicate adapter codes

If two adapters are registered under the same code, the compiler pass throws. With v2.2 you get both service IDs in the message — keep that in mind when debugging DI extensions from third-party bundles.

on_miss semantics

• output_null (default): main output receives null; workflow continues normally.
• skip: main output is bypassed and the input is forwarded to error outputs — your workflow must declare them.
• fail: throws. Use only when a miss genuinely indicates a broken pipeline.

Testing

Mock GetTask/SetTask in isolation, or use Symfony's TaskTestCase if available in your workflow testing bundle. For unit tests around AbstractCacheTask subclasses, assert that getRequiredOptions() fails fast when a required option is missing.

Extension points worth knowing

• AbstractCacheTask::getRequiredOptions() — define required options per task.
• AdapterRegistry::addAdapter() — add adapters programmatically with $serviceId for better diagnostics.
• The bundle's compiler pass — register adapters by code via configuration; extend it only if you need dynamic registration.