1<?php
2
3namespace League\Flysystem;
4
5use InvalidArgumentException;
6
7interface FilesystemInterface
8{
9    /**
10     * Check whether a file exists.
11     *
12     * @param string $path
13     *
14     * @return bool
15     */
16    public function has($path);
17
18    /**
19     * Read a file.
20     *
21     * @param string $path The path to the file.
22     *
23     * @throws FileNotFoundException
24     *
25     * @return string|false The file contents or false on failure.
26     */
27    public function read($path);
28
29    /**
30     * Retrieves a read-stream for a path.
31     *
32     * @param string $path The path to the file.
33     *
34     * @throws FileNotFoundException
35     *
36     * @return resource|false The path resource or false on failure.
37     */
38    public function readStream($path);
39
40    /**
41     * List contents of a directory.
42     *
43     * @param string $directory The directory to list.
44     * @param bool   $recursive Whether to list recursively.
45     *
46     * @return array A list of file metadata.
47     */
48    public function listContents($directory = '', $recursive = false);
49
50    /**
51     * Get a file's metadata.
52     *
53     * @param string $path The path to the file.
54     *
55     * @throws FileNotFoundException
56     *
57     * @return array|false The file metadata or false on failure.
58     */
59    public function getMetadata($path);
60
61    /**
62     * Get a file's size.
63     *
64     * @param string $path The path to the file.
65     *
66     * @throws FileNotFoundException
67     *
68     * @return int|false The file size or false on failure.
69     */
70    public function getSize($path);
71
72    /**
73     * Get a file's mime-type.
74     *
75     * @param string $path The path to the file.
76     *
77     * @throws FileNotFoundException
78     *
79     * @return string|false The file mime-type or false on failure.
80     */
81    public function getMimetype($path);
82
83    /**
84     * Get a file's timestamp.
85     *
86     * @param string $path The path to the file.
87     *
88     * @throws FileNotFoundException
89     *
90     * @return int|false The timestamp or false on failure.
91     */
92    public function getTimestamp($path);
93
94    /**
95     * Get a file's visibility.
96     *
97     * @param string $path The path to the file.
98     *
99     * @throws FileNotFoundException
100     *
101     * @return string|false The visibility (public|private) or false on failure.
102     */
103    public function getVisibility($path);
104
105    /**
106     * Write a new file.
107     *
108     * @param string $path     The path of the new file.
109     * @param string $contents The file contents.
110     * @param array  $config   An optional configuration array.
111     *
112     * @throws FileExistsException
113     *
114     * @return bool True on success, false on failure.
115     */
116    public function write($path, $contents, array $config = []);
117
118    /**
119     * Write a new file using a stream.
120     *
121     * @param string   $path     The path of the new file.
122     * @param resource $resource The file handle.
123     * @param array    $config   An optional configuration array.
124     *
125     * @throws InvalidArgumentException If $resource is not a file handle.
126     * @throws FileExistsException
127     *
128     * @return bool True on success, false on failure.
129     */
130    public function writeStream($path, $resource, array $config = []);
131
132    /**
133     * Update an existing file.
134     *
135     * @param string $path     The path of the existing file.
136     * @param string $contents The file contents.
137     * @param array  $config   An optional configuration array.
138     *
139     * @throws FileNotFoundException
140     *
141     * @return bool True on success, false on failure.
142     */
143    public function update($path, $contents, array $config = []);
144
145    /**
146     * Update an existing file using a stream.
147     *
148     * @param string   $path     The path of the existing file.
149     * @param resource $resource The file handle.
150     * @param array    $config   An optional configuration array.
151     *
152     * @throws InvalidArgumentException If $resource is not a file handle.
153     * @throws FileNotFoundException
154     *
155     * @return bool True on success, false on failure.
156     */
157    public function updateStream($path, $resource, array $config = []);
158
159    /**
160     * Rename a file.
161     *
162     * @param string $path    Path to the existing file.
163     * @param string $newpath The new path of the file.
164     *
165     * @throws FileExistsException   Thrown if $newpath exists.
166     * @throws FileNotFoundException Thrown if $path does not exist.
167     *
168     * @return bool True on success, false on failure.
169     */
170    public function rename($path, $newpath);
171
172    /**
173     * Copy a file.
174     *
175     * @param string $path    Path to the existing file.
176     * @param string $newpath The new path of the file.
177     *
178     * @throws FileExistsException   Thrown if $newpath exists.
179     * @throws FileNotFoundException Thrown if $path does not exist.
180     *
181     * @return bool True on success, false on failure.
182     */
183    public function copy($path, $newpath);
184
185    /**
186     * Delete a file.
187     *
188     * @param string $path
189     *
190     * @throws FileNotFoundException
191     *
192     * @return bool True on success, false on failure.
193     */
194    public function delete($path);
195
196    /**
197     * Delete a directory.
198     *
199     * @param string $dirname
200     *
201     * @throws RootViolationException Thrown if $dirname is empty.
202     *
203     * @return bool True on success, false on failure.
204     */
205    public function deleteDir($dirname);
206
207    /**
208     * Create a directory.
209     *
210     * @param string $dirname The name of the new directory.
211     * @param array  $config  An optional configuration array.
212     *
213     * @return bool True on success, false on failure.
214     */
215    public function createDir($dirname, array $config = []);
216
217    /**
218     * Set the visibility for a file.
219     *
220     * @param string $path       The path to the file.
221     * @param string $visibility One of 'public' or 'private'.
222     *
223     * @throws FileNotFoundException
224     *
225     * @return bool True on success, false on failure.
226     */
227    public function setVisibility($path, $visibility);
228
229    /**
230     * Create a file or update if exists.
231     *
232     * @param string $path     The path to the file.
233     * @param string $contents The file contents.
234     * @param array  $config   An optional configuration array.
235     *
236     * @return bool True on success, false on failure.
237     */
238    public function put($path, $contents, array $config = []);
239
240    /**
241     * Create a file or update if exists.
242     *
243     * @param string   $path     The path to the file.
244     * @param resource $resource The file handle.
245     * @param array    $config   An optional configuration array.
246     *
247     * @throws InvalidArgumentException Thrown if $resource is not a resource.
248     *
249     * @return bool True on success, false on failure.
250     */
251    public function putStream($path, $resource, array $config = []);
252
253    /**
254     * Read and delete a file.
255     *
256     * @param string $path The path to the file.
257     *
258     * @throws FileNotFoundException
259     *
260     * @return string|false The file contents, or false on failure.
261     */
262    public function readAndDelete($path);
263
264    /**
265     * Get a file/directory handler.
266     *
267     * @deprecated
268     *
269     * @param string  $path    The path to the file.
270     * @param Handler $handler An optional existing handler to populate.
271     *
272     * @return Handler Either a file or directory handler.
273     */
274    public function get($path, Handler $handler = null);
275
276    /**
277     * Register a plugin.
278     *
279     * @param PluginInterface $plugin The plugin to register.
280     *
281     * @return $this
282     */
283    public function addPlugin(PluginInterface $plugin);
284}
285