In PSR-6, what do CacheItemPoolInterface::saveDeferred() and commit() do, and what may a pool do with deferred items before commit()?

## Immediate versus deferred saves In **PSR-6**, a `CacheItemPoolInterface` offers two ways to persist an item you obtained with `getItem()` and changed with `set()`: | Method | Effect | Returns | |---|---|---| | `save($item)` | persists the item immediately | `true` on success, `false` on error | | `saveDeferred($item)` | queues the item to be persisted later | `false` if it could not be queued, or if a commit was attempted and failed; `true` otherwise | | `commit()` | persists every outstanding deferred item | `true` if all were saved or there were none; `false` otherwise | The point of deferral is **batching**. Many storage engines can write many keys in one round trip; a pool that collects deferred items can send them together instead of one network call per item. ## What the specification promises about deferred items The **Deferred** definition in PSR-6 sets these rules: 1. A pool **may** delay persisting a deferred item to take advantage of bulk operations. 2. It **must** ensure deferred items are eventually persisted and data is not lost. 3. It **may** persist them before the caller asks, using any logic it likes: an object destructor, persisting everything on the next `save()`, a timeout, or a maximum-items check. 4. When the caller invokes `commit()`, all outstanding deferred items **must** be persisted. 5. A request for a deferred item **must** return the deferred, not-yet-persisted item. Rule 5 means code in the same process reads its own writes: after `saveDeferred()`, `getItem()` for that key sees the new value even if storage has not been touched yet. ## What callers should and should not assume - Do **not** assume nothing is written until `commit()`: rule 3 allows early persistence, so deferral is not a transaction and there is no rollback. - Do **not** rely on a destructor to flush: some pools do, but the specification only lists it as one permitted strategy. Call `commit()` explicitly when the batch is done. - **Do** check the return value of `commit()` when correctness depends on the writes; errors surface as `false`, not exceptions. - Other processes cannot see deferred items until they are persisted; in practice only the pool object holding the queue can answer with them. ## Why failures are booleans PSR-6's error-handling section says caching should never be a critical part of application functionality. Implementations **must not** throw exceptions other than those the interfaces define, and **should** trap errors from the underlying store rather than let them bubble, logging or reporting them instead. So a storage outage typically appears as `save()`, `saveDeferred()` or `commit()` returning `false`, and a later `getItem()` returning a miss. The exceptions that can reach callers implement `Psr\Cache\CacheException`, and an illegal key raises `Psr\Cache\InvalidArgumentException`. ## Example: warming many rates at once An exchange-rate library can warm its cache for every currency pair after one bulk API call: ```php foreach ($rates as $pair => $rate) { $item = $pool->getItem('rate.' . $pair); $pool->saveDeferred($item->set($rate)->expiresAfter(600)); } if (!$pool->commit()) { $this->logger->warning('Rate cache warm-up was not fully persisted'); } ``` With a backend that supports multi-key writes, this becomes one round trip instead of one per pair. ## Comparison with PSR-16 PSR-16 has no deferred mode. Its batch equivalent is `setMultiple($values, $ttl = null)`, which writes a set of key/value pairs in one call and returns a boolean. That covers the "many writes, one round trip" case, but not incremental queuing across different parts of the code followed by a single flush. ## Checklist - Use `saveDeferred()` for many writes that belong together; `save()` for single writes. - Always finish a batch with `commit()` and check its result. - Treat deferral as batching, not as a transaction.