1	<?php
2	declare(strict_types=1);
3	/**
4	* Pop PHP Framework (https://www.popphp.org/)
5	*
6	* @link       https://github.com/popphp/popphp-framework
7	* @author     Nick Sagona, III <nick@popphp.org>
8	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
9	* @license    https://www.popphp.org/license     New BSD License
10	*/
11
12	/**
13	* @namespace
14	*/
15	namespace Pop\Storage;
16
17	/**
18	* Storage interface
19	*
20	* @category   Pop
21	* @package    Pop\Storage
22	* @author     Nick Sagona, III <nick@popphp.org>
23	* @copyright  Copyright (c) 2009-2026 Nick Sagona, III
24	* @license    https://www.popphp.org/license     New BSD License
25	* @version    3.0.0
26	*/
27	interface StorageInterface
28	{
29
30	/**
31	* Set base directory
32	*
33	* @param  ?string $directory
34	* @return void
35	*/
36	public function setBaseDir(?string $directory = null): void;
37
38	/**
39	* Get base directory
40	*
41	* @return ?string
42	*/
43	public function getBaseDir(): ?string;
44
45	/**
46	* Get current directory
47	*
48	* @return ?string
49	*/
50	public function getCurrentDir(): ?string;
51
52	/**
53	* Change directory
54	*
55	* @param  ?string $directory
56	* @return void
57	*/
58	public function chdir(?string $directory = null): void;
59
60	/**
61	* Make directory
62	*
63	* @param  string $directory
64	* @return void
65	*/
66	public function mkdir(string $directory): void;
67
68	/**
69	* Remove a directory
70	*
71	* @param  string $directory
72	* @return void
73	*/
74	public function rmdir(string $directory): void;
75
76	/**
77	* List all
78	*
79	* @param  ?string $search
80	* @param  bool    $recursive
81	* @return array
82	*/
83	public function listAll(?string $search = null, bool $recursive = false): array;
84
85	/**
86	* List directories
87	*
88	* @param  ?string $search
89	* @param  bool    $recursive
90	* @return array
91	*/
92	public function listDirs(?string $search = null, bool $recursive = false): array;
93
94	/**
95	* List files
96	*
97	* @param  ?string $search
98	* @param  bool    $recursive
99	* @return array
100	*/
101	public function listFiles(?string $search = null, bool $recursive = false): array;
102
103	/**
104	* Put file
105	*
106	* @param  string $fileFrom
107	* @param  bool   $copy
108	* @return void
109	*/
110	public function putFile(string $fileFrom, bool $copy = true): void;
111
112	/**
113	* Put file contents
114	*
115	* @param  string $filename
116	* @param  string $fileContents
117	* @return void
118	*/
119	public function putFileContents(string $filename, string $fileContents): void;
120
121	/**
122	* Put file from a stream resource
123	*
124	* @param  string $filename
125	* @param  mixed  $resource
126	* @return void
127	*/
128	public function putFileStream(string $filename, mixed $resource): void;
129
130	/**
131	* Upload file from server request $_FILES['file']
132	*
133	* @param  array $file
134	* @return void
135	*/
136	public function uploadFile(array $file): void;
137
138	/**
139	* Copy file
140	*
141	* @param  string $sourceFile
142	* @param  string $destFile
143	* @return void
144	*/
145	public function copyFile(string $sourceFile, string $destFile): void;
146
147
148	/**
149	* Copy file to a location external to the current location
150	*
151	* @param  string $sourceFile
152	* @param  string $externalFile
153	* @return void
154	*/
155	public function copyFileToExternal(string $sourceFile, string $externalFile): void;
156
157
158	/**
159	* Copy file from a location external to the current location
160	*
161	* @param  string $externalFile
162	* @param  string $destFile
163	* @return void
164	*/
165	public function copyFileFromExternal(string $externalFile, string $destFile): void;
166
167	/**
168	* Move file to a location external to the current location
169	*
170	* @param  string $sourceFile
171	* @param  string $externalFile
172	* @return void
173	*/
174	public function moveFileToExternal(string $sourceFile, string $externalFile): void;
175
176	/**
177	* Move file from a location external to the current location
178	*
179	* @param  string $externalFile
180	* @param  string $destFile
181	* @return void
182	*/
183	public function moveFileFromExternal(string $externalFile, string $destFile): void;
184
185	/**
186	* Rename file
187	*
188	* @param  string $oldFile
189	* @param  string $newFile
190	* @return void
191	*/
192	public function renameFile(string $oldFile, string $newFile): void;
193
194	/**
195	* Replace file
196	*
197	* @param  string $filename
198	* @param  string $fileContents
199	* @return void
200	*/
201	public function replaceFileContents(string $filename, string $fileContents): void;
202
203	/**
204	* Delete file
205	*
206	* @param  string $filename
207	* @return void
208	*/
209	public function deleteFile(string $filename): void;
210
211	/**
212	* Fetch file contents
213	*
214	* @param  string $filename
215	* @return mixed
216	*/
217	public function fetchFile(string $filename): mixed;
218
219	/**
220	* Fetch file as a stream resource
221	*
222	* @param  string $filename
223	* @return mixed
224	*/
225	public function fetchFileStream(string $filename): mixed;
226
227	/**
228	* Fetch file info
229	*
230	* @param  string $filename
231	* @return array
232	*/
233	public function fetchFileInfo(string $filename): array;
234
235	/**
236	* Get a temporary (presigned) URL for the file, valid for $expiresInSeconds
237	*
238	* @param  string $filename
239	* @param  int    $expiresInSeconds
240	* @return string
241	*/
242	public function getTemporaryUrl(string $filename, int $expiresInSeconds = 900): string;
243
244	/**
245	* File exists
246	*
247	* @param  string $filename
248	* @return bool
249	*/
250	public function fileExists(string $filename): bool;
251
252	/**
253	* Check if is a directory
254	*
255	* @param  string $directory
256	* @return bool
257	*/
258	public function isDir(string $directory): bool;
259
260	/**
261	* Check if is a file
262	*
263	* @param  string $filename
264	* @return bool
265	*/
266	public function isFile(string $filename): bool;
267
268	/**
269	* Get file size
270	*
271	* @param  string $filename
272	* @return int
273	*/
274	public function getFileSize(string $filename): int;
275
276	/**
277	* Get file type
278	*
279	* @param  string $filename
280	* @return string
281	*/
282	public function getFileType(string $filename): string;
283
284	/**
285	* Get file modified time
286	*
287	* @param  string $filename
288	* @return int|string
289	*/
290	public function getFileMTime(string $filename): int|string;
291
292	/**
293	* Create MD5 checksum of the file
294	*
295	* @param  string $filename
296	* @return string
297	*/
298	public function md5File(string $filename): string;
299
300	}