1	<?php
2	/**
3	*
4	* This file is part of the phpBB Forum Software package.
5	*
6	* @copyright (c) phpBB Limited <https://www.phpbb.com>
7	* @license GNU General Public License, version 2 (GPL-2.0)
8	*
9	* For full copyright and license information, please see
10	* the docs/CREDITS.txt file.
11	*
12	*/
13
14	namespace phpbb\filesystem;
15
16	/**
17	* Interface for phpBB's filesystem service
18	*/
19	interface filesystem_interface
20	{
21	/**
22	* chmod all permissions flag
23	*
24	* @var int
25	*/
26	const CHMOD_ALL = 7;
27
28	/**
29	* chmod read permissions flag
30	*
31	* @var int
32	*/
33	const CHMOD_READ = 4;
34
35	/**
36	* chmod write permissions flag
37	*
38	* @var int
39	*/
40	const CHMOD_WRITE = 2;
41
42	/**
43	* chmod execute permissions flag
44	*
45	* @var int
46	*/
47	const CHMOD_EXECUTE = 1;
48
49	/**
50	* Change owner group of files/directories
51	*
52	* @param string|array|\Traversable    $files        The file(s)/directorie(s) to change group
53	* @param string                    $group        The group that should own the files/directories
54	* @param bool                         $recursive    If the group should be changed recursively
55	* @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
56	*                                                             retrieved by filesystem_exception::get_filename()
57	*/
58	public function chgrp($files, $group, $recursive = false);
59
60	/**
61	* Global function for chmodding directories and files for internal use
62	*
63	* The function accepts filesystem_interface::CHMOD_ flags in the permission argument
64	* or the user can specify octal values (or any integer if it makes sense). All directories will have
65	* an execution bit appended, if the user group (owner, group or other) has any bit specified.
66	*
67	* @param string|array|\Traversable    $files                The file/directory to be chmodded
68	* @param int                        $perms                Permissions to set
69	* @param bool                        $recursive            If the permissions should be changed recursively
70	* @param bool                        $force_chmod_link    Try to apply permissions to symlinks as well
71	*
72	* @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
73	*                                                             retrieved by filesystem_exception::get_filename()
74	*/
75	public function chmod($files, $perms = null, $recursive = false, $force_chmod_link = false);
76
77	/**
78	* Change owner group of files/directories
79	*
80	* @param string|array|\Traversable    $files        The file(s)/directorie(s) to change group
81	* @param string                    $user        The owner user name
82	* @param bool                         $recursive    Whether change the owner recursively or not
83	*
84	* @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
85	*                                                             retrieved by filesystem_exception::get_filename()
86	*/
87	public function chown($files, $user, $recursive = false);
88
89	/**
90	* Eliminates useless . and .. components from specified path.
91	*
92	* @deprecated 3.3.0-a1 (To be removed: 4.0.0)
93	*
94	* @param string $path Path to clean
95	*
96	* @return string Cleaned path
97	*/
98	public function clean_path($path);
99
100	/**
101	* Copies a file.
102	*
103	* This method only copies the file if the origin file is newer than the target file.
104	*
105	* By default, if the target already exists, it is not overridden.
106	*
107	* @param string    $origin_file    The original filename
108	* @param string    $target_file    The target filename
109	* @param bool        $override        Whether to override an existing file or not
110	*
111	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied
112	*/
113	public function copy($origin_file, $target_file, $override = false);
114
115	/**
116	* Atomically dumps content into a file.
117	*
118	* @param string    $filename    The file to be written to.
119	* @param string    $content    The data to write into the file.
120	*
121	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be written
122	*/
123	public function dump_file($filename, $content);
124
125	/**
126	* Checks the existence of files or directories.
127	*
128	* @param string|array|\Traversable    $files    files/directories to check
129	*
130	* @return bool    Returns true if all files/directories exist, false otherwise
131	*/
132	public function exists($files);
133
134	/**
135	* Checks if a path is absolute or not
136	*
137	* @deprecated 3.3.0-a1 (To be removed: 4.0.0)
138	*
139	* @param string    $path    Path to check
140	*
141	* @return    bool    true if the path is absolute, false otherwise
142	*/
143	public function is_absolute_path($path);
144
145	/**
146	* Checks if files/directories are readable
147	*
148	* @param string|array|\Traversable    $files        files/directories to check
149	* @param bool                        $recursive    Whether or not directories should be checked recursively
150	*
151	* @return bool True when the files/directories are readable, otherwise false.
152	*/
153	public function is_readable($files, $recursive = false);
154
155	/**
156	* Test if a file/directory is writable
157	*
158	* @param string|array|\Traversable    $files        files/directories to perform write test on
159	* @param bool                        $recursive    Whether or not directories should be checked recursively
160	*
161	* @return bool True when the files/directories are writable, otherwise false.
162	*/
163	public function is_writable($files, $recursive = false);
164
165	/**
166	* Given an existing path, convert it to a path relative to a given starting path
167	*
168	* @deprecated 3.3.0-a1 (To be removed: 4.0.0)
169	*
170	* @param string $end_path        Absolute path of target
171	* @param string $start_path    Absolute path where traversal begins
172	*
173	* @return string Path of target relative to starting path
174	*/
175	public function make_path_relative($end_path, $start_path);
176
177	/**
178	* Mirrors a directory to another.
179	*
180	* @param string            $origin_dir    The origin directory
181	* @param string            $target_dir    The target directory
182	* @param \Traversable|null    $iterator    A Traversable instance
183	* @param array                $options    An array of boolean options
184	*                                        Valid options are:
185	*                                            - $options['override'] Whether to override an existing file on copy or not (see copy())
186	*                                            - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink())
187	*                                            - $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
188	*
189	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied.
190	*                                                             The filename which triggered the error can be
191	*                                                             retrieved by filesystem_exception::get_filename()
192	*/
193	public function mirror($origin_dir, $target_dir, \Traversable|null $iterator = null, $options = array());
194
195	/**
196	* Creates a directory recursively.
197	*
198	* @param string|array|\Traversable    $dirs    The directory path
199	* @param int                        $mode    The directory mode
200	*
201	* @throws \phpbb\filesystem\exception\filesystem_exception On any directory creation failure
202	*                                                             The filename which triggered the error can be
203	*                                                             retrieved by filesystem_exception::get_filename()
204	*/
205	public function mkdir($dirs, $mode = 0777);
206
207	/**
208	* Global function for chmodding directories and files for internal use
209	*
210	* This function determines owner and group whom the file belongs to and user and group of PHP and then set safest possible file permissions.
211	* The function determines owner and group from common.php file and sets the same to the provided file.
212	* The function uses bit fields to build the permissions.
213	* The function sets the appropriate execute bit on directories.
214	*
215	* Supported constants representing bit fields are:
216	*
217	* filesystem_interface::CHMOD_ALL - all permissions (7)
218	* filesystem_interface::CHMOD_READ - read permission (4)
219	* filesystem_interface::CHMOD_WRITE - write permission (2)
220	* filesystem_interface::CHMOD_EXECUTE - execute permission (1)
221	*
222	* NOTE: The function uses POSIX extension and fileowner()/filegroup() functions. If any of them is disabled, this function tries to build proper permissions, by calling is_readable() and is_writable() functions.
223	*
224	* @param string|array|\Traversable    $file                The file/directory to be chmodded
225	* @param int                        $perms                Permissions to set
226	* @param bool                        $recursive            If the permissions should be changed recursively
227	* @param bool                        $force_chmod_link    Try to apply permissions to symlinks as well
228	*
229	* @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
230	*                                                             retrieved by filesystem_exception::get_filename()
231	*/
232	public function phpbb_chmod($file, $perms = null, $recursive = false, $force_chmod_link = false);
233
234	/**
235	* A wrapper for PHP's realpath
236	*
237	* @deprecated 3.3.0-a1 (To be removed: 4.0.0)
238	*
239	* Try to resolve realpath when PHP's realpath is not available, or
240	* known to be buggy.
241	*
242	* @param ?string    $path    Path to resolve
243	*
244	* @return string|false    Resolved path or false if path could not be resolved
245	*/
246	public function realpath($path);
247
248	/**
249	* Removes files or directories.
250	*
251	* @param string|array|\Traversable    $files    A filename, an array of files, or a \Traversable instance to remove
252	*
253	* @throws \phpbb\filesystem\exception\filesystem_exception When removal fails.
254	*                                                             The filename which triggered the error can be
255	*                                                             retrieved by filesystem_exception::get_filename()
256	*/
257	public function remove($files);
258
259	/**
260	* Renames a file or a directory.
261	*
262	* @param string    $origin        The origin filename or directory
263	* @param string    $target        The new filename or directory
264	* @param bool        $overwrite    Whether to overwrite the target if it already exists
265	*
266	* @throws \phpbb\filesystem\exception\filesystem_exception    When target file or directory already exists,
267	*                                                             or origin cannot be renamed.
268	*/
269	public function rename($origin, $target, $overwrite = false);
270
271	/**
272	* Creates a symbolic link or copy a directory.
273	*
274	* @param string    $origin_dir            The origin directory path
275	* @param string    $target_dir            The symbolic link name
276	* @param bool        $copy_on_windows    Whether to copy files if on Windows
277	*
278	* @throws \phpbb\filesystem\exception\filesystem_exception When symlink fails
279	*/
280	public function symlink($origin_dir, $target_dir, $copy_on_windows = false);
281
282	/**
283	* Sets access and modification time of file.
284	*
285	* @param string|array|\Traversable    $files            A filename, an array of files, or a \Traversable instance to create
286	* @param int                        $time            The touch time as a Unix timestamp
287	* @param int                        $access_time    The access time as a Unix timestamp
288	*
289	* @throws \phpbb\filesystem\exception\filesystem_exception    When touch fails
290	*/
291	public function touch($files, $time = null, $access_time = null);
292	}