Add ETag-only cache mode

[GrahamCampbell]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Related tickets	-
Documentation	README updated in this pull request
License	MIT

What's in this PR?

Adds an etag_only cache option. When enabled, the plugin only stores responses with an ETag header, always revalidates cached entries with If-None-Match, and only serves cached bodies after the origin returns 304 Not Modified.

Why?

Some API clients need local response bodies for conditional requests, but cannot safely use freshness-based caching. This mode avoids caching responses without ETags and avoids serving cached bodies without origin confirmation.

Example Usage

$plugin = CachePlugin::clientCache($pool, $streamFactory, [
    'etag_only' => true,
]);

Checklist

• Updated CHANGELOG.md to describe BC breaks / deprecations | new feature | bugfix
• Documentation pull request created (if not simply a bugfix)

To Do

• Create external documentation PR if maintainers want this covered outside the README.

[dbu]

thanks for this contribution, i see the use case. i am not too happy with how the code creates if/else in several places. i wonder if we could extract the shared behaviour into an @internal base class and extend CachePlugin from that and a new EtagCachePlugin with the other behaviour, instead of a boolean flag. i don't see that we would need to mix the two behaviours, so having separate classes to select would make things more clear. wdyt?

[GrahamCampbell]

OK, I've applied that refactor, and corrected deprecation notes to say things are going away in 3.0, not 2.0 - we already did a 2.0 release and never removed all the deprecated stuff from 1.x.

[dbu]

thanks a lot!

can you please add the documentation in the central doc repository as well?
https://github.com/php-http/documentation/blob/main/plugins/cache.rst

[dbu]

https://github.com/php-http/cache-plugin/releases/tag/2.1.0

[dbu]

i removed the doc note from the readme again - the readme does not contain documentation but refers to the central doc page. it would be inconsistent to just mention this one feature in the readme

[dbu]

and do you have time to expose the functionality in https://github.com/php-http/HttplugBundle as well? i am not sure whether we should handle it as a separate plugin or an option for the cache plugin. probably an option, as all the other options are the same regardless of which version is used.

though respect_response_cache_directives sounds like it is not relevant for the etag cache, or is it?