1	<?php
2
3	/**
4	* Storage interface for abstracting file storage operations.
5	*
6	* This Source Code Form is subject to the terms of the Mozilla Public License,
7	* v. 2.0. If a copy of the MPL was not distributed with this file, You can
8	* obtain one at https://mozilla.org/MPL/2.0/.
9	*
10	* @package   phpMyFAQ
11	* @author    Thorsten Rinne <thorsten@phpmyfaq.de>
12	* @copyright 2026 phpMyFAQ Team
13	* @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
14	* @link      https://www.phpmyfaq.de
15	* @since     2026-02-08
16	*/
17
18	declare(strict_types=1);
19
20	namespace phpMyFAQ\Storage;
21
22	/**
23	* Interface StorageInterface
24	*
25	* @package phpMyFAQ\Storage
26	*/
27	interface StorageInterface
28	{
29	/**
30	* Write string contents to a path.
31	*
32	* @param string $path     the storage path
33	* @param string $contents the file contents
34	* @throws StorageException
35	*/
36	public function put(string $path, string $contents): bool;
37
38	/**
39	* Write from a stream resource for large files.
40	*
41	* @param string $path   the storage path
42	* @param mixed  $stream a readable stream resource
43	* @throws StorageException
44	*/
45	public function putStream(string $path, mixed $stream): bool;
46
47	/**
48	* Read the entire file contents.
49	*
50	* @param string $path the storage path
51	* @throws StorageException
52	*/
53	public function get(string $path): string;
54
55	/**
56	* Delete a file.
57	*
58	* @param string $path the storage path
59	* @throws StorageException
60	*/
61	public function delete(string $path): bool;
62
63	/**
64	* Check if a file exists.
65	*
66	* @param string $path the storage path
67	*/
68	public function exists(string $path): bool;
69
70	/**
71	* Get the public/accessible URL for a file.
72	*
73	* @param string $path the storage path
74	* @throws StorageException
75	*/
76	public function url(string $path): string;
77
78	/**
79	* Get file size in bytes.
80	*
81	* @param string $path the storage path
82	* @throws StorageException
83	*/
84	public function size(string $path): int;
85	}