feat(task) #30 #31 #32 Options given by the input only, key validation, GetTask on_miss and SetTask expires_after

[njoubert-cleverage]

Description

Fixes #30.
Fixes #31.
Fixes #32.

Grouped in one PR because the three changes modify the same tasks, tests and documentation pages.

#30: options given by the input only, key validation

• AbstractCacheTask: adapter and key are no longer required at configuration level; they are required once merged with the input, in getMergedOptions() (new getRequiredOptions() method, overridden by SetTask to add value). No more placeholders (key: '', value: ~) in the configurations.
• getMergedOptions() validates the key with CacheItem::validateKey(): Symfony adapters only validate the keys with assert() (The documentation states that invalid cache keys always throw an exception #28), so an empty key or a key with a reserved character was silently accepted in production. It now always throws a Psr\Cache\InvalidArgumentException.

#31: GetTask on_miss option

• output_null (default, current behaviour), skip (skip the item and send the input to the error outputs, as FilterTask does: "cache-aside" pattern), fail (\UnexpectedValueException). Based on isHit(): a stored null value is always output.

#32: SetTask expires_after option

• int (seconds, strictly positive) or null (default: default lifetime of the adapter), passed to expiresAfter(). Can be given by the input for a lifetime per item.

Tests: options from the input only, required options on execution, invalid keys (empty, reserved character: they pass with zend.assertions=-1), the three on_miss values (including a stored null with skip), expires_after from the options and from the input, invalid expires_after values. 60 tests, 78/78 lines.

Documentation: get_task.md, set_task.md (options, examples without placeholders, cache-aside and expiration examples, notes), adapter.md, index.md (custom tasks), both cookbooks (no placeholders, on_miss: skip instead of SkipEmptyTask).

Checked with process-bundle-demo (with php -d zend.assertions=-1), see the demo PR:

• demo.cache.set_get without placeholders: unchanged output
• demo.cache.get_on_miss: key1 and key2 are computed and stored, the second key1 is read from the cache
• demo.cache.set_expires_after: the item is found right after SetTask, and missing after a 2 seconds pause
• demo.cache.set_invalid_key: Cache key "ABC/001" contains reserved characters "{}()/\@:". (stored silently before)

Requirements

• Documentation updates
  • Reference
  • Changelog
• Unit tests

Breaking changes

• An invalid key (e.g. a placeholder '' not overridden by the input, or a key with a reserved character) now always throws, also in production; it was silently accepted when assertions were disabled.
• A missing adapter / key / value is reported on execution instead of initialization.
• A custom task extending AbstractCacheTask no longer gets adapter and key required at initialization; getMergedOptions() requires the options returned by getRequiredOptions().

Configurations with placeholders overridden by the input keep working. on_miss and expires_after default to the current behaviour.

🤖 Generated with Claude Code