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	* @param string $path Path to clean
93	*
94	* @return string Cleaned path
95	*/
96	public function clean_path($path);
97
98	/**
99	* Copies a file.
100	*
101	* This method only copies the file if the origin file is newer than the target file.
102	*
103	* By default, if the target already exists, it is not overridden.
104	*
105	* @param string    $origin_file    The original filename
106	* @param string    $target_file    The target filename
107	* @param bool        $override        Whether to override an existing file or not
108	*
109	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied
110	*/
111	public function copy($origin_file, $target_file, $override = false);
112
113	/**
114	* Atomically dumps content into a file.
115	*
116	* @param string    $filename    The file to be written to.
117	* @param string    $content    The data to write into the file.
118	*
119	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be written
120	*/
121	public function dump_file($filename, $content);
122
123	/**
124	* Checks the existence of files or directories.
125	*
126	* @param string|array|\Traversable    $files    files/directories to check
127	*
128	* @return bool    Returns true if all files/directories exist, false otherwise
129	*/
130	public function exists($files);
131
132	/**
133	* Checks if a path is absolute or not
134	*
135	* @param string    $path    Path to check
136	*
137	* @return    bool    true if the path is absolute, false otherwise
138	*/
139	public function is_absolute_path($path);
140
141	/**
142	* Checks if files/directories are readable
143	*
144	* @param string|array|\Traversable    $files        files/directories to check
145	* @param bool                        $recursive    Whether or not directories should be checked recursively
146	*
147	* @return bool True when the files/directories are readable, otherwise false.
148	*/
149	public function is_readable($files, $recursive = false);
150
151	/**
152	* Test if a file/directory is writable
153	*
154	* @param string|array|\Traversable    $files        files/directories to perform write test on
155	* @param bool                        $recursive    Whether or not directories should be checked recursively
156	*
157	* @return bool True when the files/directories are writable, otherwise false.
158	*/
159	public function is_writable($files, $recursive = false);
160
161	/**
162	* Given an existing path, convert it to a path relative to a given starting path
163	*
164	* @param string $end_path        Absolute path of target
165	* @param string $start_path    Absolute path where traversal begins
166	*
167	* @return string Path of target relative to starting path
168	*/
169	public function make_path_relative($end_path, $start_path);
170
171	/**
172	* Mirrors a directory to another.
173	*
174	* @param string        $origin_dir    The origin directory
175	* @param string        $target_dir    The target directory
176	* @param \Traversable    $iterator    A Traversable instance
177	* @param array            $options    An array of boolean options
178	*                                    Valid options are:
179	*                                        - $options['override'] Whether to override an existing file on copy or not (see copy())
180	*                                        - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink())
181	*                                        - $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
182	*
183	* @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied.
184	*                                                             The filename which triggered the error can be
185	*                                                             retrieved by filesystem_exception::get_filename()
186	*/
187	public function mirror($origin_dir, $target_dir, \Traversable $iterator = null, $options = array());
188
189	/**
190	* Creates a directory recursively.
191	*
192	* @param string|array|\Traversable    $dirs    The directory path
193	* @param int                        $mode    The directory mode
194	*
195	* @throws \phpbb\filesystem\exception\filesystem_exception On any directory creation failure
196	*                                                             The filename which triggered the error can be
197	*                                                             retrieved by filesystem_exception::get_filename()
198	*/
199	public function mkdir($dirs, $mode = 0777);
200
201	/**
202	* Global function for chmodding directories and files for internal use
203	*
204	* This function determines owner and group whom the file belongs to and user and group of PHP and then set safest possible file permissions.
205	* The function determines owner and group from common.php file and sets the same to the provided file.
206	* The function uses bit fields to build the permissions.
207	* The function sets the appropriate execute bit on directories.
208	*
209	* Supported constants representing bit fields are:
210	*
211	* filesystem_interface::CHMOD_ALL - all permissions (7)
212	* filesystem_interface::CHMOD_READ - read permission (4)
213	* filesystem_interface::CHMOD_WRITE - write permission (2)
214	* filesystem_interface::CHMOD_EXECUTE - execute permission (1)
215	*
216	* 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.
217	*
218	* @param string|array|\Traversable    $file                The file/directory to be chmodded
219	* @param int                        $perms                Permissions to set
220	* @param bool                        $recursive            If the permissions should be changed recursively
221	* @param bool                        $force_chmod_link    Try to apply permissions to symlinks as well
222	*
223	* @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
224	*                                                             retrieved by filesystem_exception::get_filename()
225	*/
226	public function phpbb_chmod($file, $perms = null, $recursive = false, $force_chmod_link = false);
227
228	/**
229	* A wrapper for PHP's realpath
230	*
231	* Try to resolve realpath when PHP's realpath is not available, or
232	* known to be buggy.
233	*
234	* @param string    $path    Path to resolve
235	*
236	* @return string    Resolved path
237	*/
238	public function realpath($path);
239
240	/**
241	* Removes files or directories.
242	*
243	* @param string|array|\Traversable    $files    A filename, an array of files, or a \Traversable instance to remove
244	*
245	* @throws \phpbb\filesystem\exception\filesystem_exception When removal fails.
246	*                                                             The filename which triggered the error can be
247	*                                                             retrieved by filesystem_exception::get_filename()
248	*/
249	public function remove($files);
250
251	/**
252	* Renames a file or a directory.
253	*
254	* @param string    $origin        The origin filename or directory
255	* @param string    $target        The new filename or directory
256	* @param bool        $overwrite    Whether to overwrite the target if it already exists
257	*
258	* @throws \phpbb\filesystem\exception\filesystem_exception    When target file or directory already exists,
259	*                                                             or origin cannot be renamed.
260	*/
261	public function rename($origin, $target, $overwrite = false);
262
263	/**
264	* Creates a symbolic link or copy a directory.
265	*
266	* @param string    $origin_dir            The origin directory path
267	* @param string    $target_dir            The symbolic link name
268	* @param bool        $copy_on_windows    Whether to copy files if on Windows
269	*
270	* @throws \phpbb\filesystem\exception\filesystem_exception When symlink fails
271	*/
272	public function symlink($origin_dir, $target_dir, $copy_on_windows = false);
273
274	/**
275	* Sets access and modification time of file.
276	*
277	* @param string|array|\Traversable    $files            A filename, an array of files, or a \Traversable instance to create
278	* @param int                        $time            The touch time as a Unix timestamp
279	* @param int                        $access_time    The access time as a Unix timestamp
280	*
281	* @throws \phpbb\filesystem\exception\filesystem_exception    When touch fails
282	*/
283	public function touch($files, $time = null, $access_time = null);
284	}