1	<?php
2
3	declare(strict_types=1);
4
5	namespace App\Domain\Storage\Service;
6
7	use Psr\Http\Message\StreamInterface;
8	use RuntimeException;
9
10	/**
11	* Domain-shaped abstraction over file storage.
12	*
13	* Callers persist the opaque key returned by {@see store()} and pass it back
14	* to retrieve, check, or delete the file. They never construct paths from
15	* the key — that's the implementation's job and the only place path logic
16	* lives.
17	*
18	* Implementations throw {@see RuntimeException} on any unrecoverable I/O
19	* failure. Callers decide whether to surface or fall back.
20	*/
21	interface FileStorageInterface
22	{
23	/**
24	* Store a file's contents and return an opaque storage key.
25	*
26	* The extension is purely cosmetic for filesystem listings — never
27	* trusted from user input and never used to dispatch handlers. Callers
28	* that need to track the user-supplied filename must persist it
29	* separately.
30	*
31	* @param StreamInterface $stream
32	* @param string $extension
33	* @throws RuntimeException on I/O failure
34	*/
35	public function store(StreamInterface $stream, string $extension = ''): string;
36
37	/**
38	* Read a previously-stored file as a stream. The returned stream owns
39	* its underlying resource and should be consumed by the caller.
40	*
41	* @param string $key
42	* @throws RuntimeException if the key is unknown or the file is unreadable
43	*/
44	public function retrieve(string $key): StreamInterface;
45
46	public function exists(string $key): bool;
47
48	/**
49	* Delete a previously-stored file. No-op if already absent.
50	*
51	* @param string $key
52	* @throws RuntimeException only on I/O failure during deletion
53	*/
54	public function delete(string $key): void;
55	}