1	<?php
2
3	declare(strict_types=1);
4
5	namespace Phpdftk\ResourceLoader\Cache;
6
7	use Phpdftk\ResourceLoader\FetchResult;
8
9	/**
10	* Persistent cache for `FetchResult`s, keyed by canonicalised URL.
11	*
12	* Implementations:
13	*
14	*   - {@see NullCache}  — no caching, every fetch hits the network
15	*   - `FileCache`       — on-disk cache with TTL (Phase 4F.2)
16	*   - `MemoryCache`     — per-request in-memory cache (4F.2)
17	*
18	* The cache contract is intentionally narrow — get / set — so the
19	* loader stays implementation-agnostic. Cache invalidation, TTL,
20	* eviction policy, and key canonicalisation are all the backend's
21	* responsibility.
22	*/
23	interface CacheInterface
24	{
25	/**
26	* Return the cached result for `$key` if any, or null. The
27	* loader treats null as a cache miss and proceeds to fetch.
28	*/
29	public function get(string $key): ?FetchResult;
30
31	/**
32	* Store a result. Implementations may compress, hash, or
33	* otherwise transform the body — the contract is "given this
34	* key in the future, `get()` returns an equivalent result" but
35	* the bytes returned need not be identical to those stored.
36	*/
37	public function set(string $key, FetchResult $result): void;
38	}