chore(doc) #28 Invalid cache keys are only rejected by Symfony adapters when assertions are enabled

CHANGELOG.md

@@ -6,6 +6,7 @@ Latest
 * [#25](https://github.com/cleverage/cache-process-bundle/issues/25) Give the ids of both services in the error on duplicate adapter codes: the adapters are registered by a compiler pass of the bundle, `AdapterRegistry::addAdapter()` gets an optional `$serviceId` argument. Update documentation, add tests.
 
 ### Fixes
+* [#28](https://github.com/cleverage/cache-process-bundle/issues/28) Fix documentation: invalid cache keys are only rejected by Symfony adapters when assertions are enabled (an exception was documented in every case).
 * [#22](https://github.com/cleverage/cache-process-bundle/issues/22) Fix GetTask and SetTask: throw an explicit `\UnexpectedValueException` on a non-array input (a `\TypeError` was triggered by `array_merge()`). Update documentation, add tests.
 * [#23](https://github.com/cleverage/cache-process-bundle/issues/23) Fix GetTask and SetTask: validate the option values given by the input with the options resolver (they were used as is). Update documentation, add tests.
 

docs/reference/adapter.md

@@ -93,6 +93,8 @@ Notes
   (`Adapter <code> is missing`) when the task is executed.
 * The cache tasks do not handle any expiration: the lifetime of the items is the default lifetime of the decorated
   pool (`default_lifetime` of a FrameworkBundle pool, `$defaultLifetime` constructor argument of Symfony adapters).
-* Cache keys must follow the PSR-6 rules: an empty key, or a key containing one of the reserved characters
-  `{}()/\@:`, throws a `Psr\Cache\InvalidArgumentException`.
+* Cache keys must follow the PSR-6 rules: no empty key, and none of the reserved characters `{}()/\@:`. The keys are
+  validated by the decorated pool, and Symfony adapters only validate them with `assert()`: an invalid key throws a
+  `Psr\Cache\InvalidArgumentException` when assertions are enabled (`zend.assertions=1`, usual in development), but is
+  silently accepted when they are not (`zend.assertions=-1`, production `php.ini`).
 * Only the PSR-6 methods are forwarded by the base class: tag-aware features of the decorated pool are not exposed.

docs/reference/tasks/get_task.md

@@ -85,7 +85,9 @@ Notes
 -----
 
 * `adapter` and `key` are required at configuration level, even when they are always given by the input: set them to
-  a placeholder value (e.g. `key: ''`).
+  a placeholder value (e.g. `key: ''`). If the input does not override the placeholder key, the empty key is rejected
+  only when assertions are enabled (see [Adapter](../adapter.md#notes)): in production, the item stored under the
+  empty key is read.
 * A missing key and an item stored with a `null` value both output `null`. Chain a
   [SkipEmptyTask](https://github.com/cleverage/process-bundle/blob/main/docs/reference/tasks/skip_empty_task.md) to
   stop the branch when nothing is found.

docs/reference/tasks/set_task.md

@@ -89,7 +89,8 @@ Notes
 
 * `adapter`, `key` and `value` are required at configuration level, even when they are always given by the input:
   set them to a placeholder value (e.g. `key: ''`, `value: ~`). If the input does not override the placeholder key,
-  the empty key throws a `Psr\Cache\InvalidArgumentException`.
+  the empty key is rejected only when assertions are enabled (see [Adapter](../adapter.md#notes)): in production, every
+  item is stored under the same empty key.
 * No expiration is set on the item: its lifetime is the default lifetime of the adapter (see
   [Adapter](../adapter.md#notes)).
 * The item is saved immediately (`save()`, not `saveDeferred()`), an existing item with the same key is overwritten.