<?php
/**
 *
 * This file is part of the phpBB Forum Software package.
 *
 * @copyright (c) phpBB Limited <https://www.phpbb.com>
 * @license GNU General Public License, version 2 (GPL-2.0)
 *
 * For full copyright and license information, please see
 * the docs/CREDITS.txt file.
 *
 */

namespace phpbb\filesystem;

/**
 * Interface for phpBB's filesystem service
 */
interface filesystem_interface
{
	/**
	 * chmod all permissions flag
	 *
	 * @var int
	 */
	const CHMOD_ALL = 7;

	/**
	 * chmod read permissions flag
	 *
	 * @var int
	 */
	const CHMOD_READ = 4;

	/**
	 * chmod write permissions flag
	 *
	 * @var int
	 */
	const CHMOD_WRITE = 2;

	/**
	 * chmod execute permissions flag
	 *
	 * @var int
	 */
	const CHMOD_EXECUTE = 1;

	/**
	 * Change owner group of files/directories
	 *
	 * @param string|array|\Traversable	$files		The file(s)/directorie(s) to change group
	 * @param string					$group		The group that should own the files/directories
	 * @param bool 						$recursive	If the group should be changed recursively
	 * @throws \phpbb\filesystem\exception\filesystem_exception	the filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function chgrp($files, $group, $recursive = false);

	/**
	 * Global function for chmodding directories and files for internal use
	 *
	 * The function accepts filesystem_interface::CHMOD_ flags in the permission argument
	 * or the user can specify octal values (or any integer if it makes sense). All directories will have
	 * an execution bit appended, if the user group (owner, group or other) has any bit specified.
	 *
	 * @param string|array|\Traversable	$files				The file/directory to be chmodded
	 * @param int						$perms				Permissions to set
	 * @param bool						$recursive			If the permissions should be changed recursively
	 * @param bool						$force_chmod_link	Try to apply permissions to symlinks as well
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception	the filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function chmod($files, $perms = null, $recursive = false, $force_chmod_link = false);

	/**
	 * Change owner group of files/directories
	 *
	 * @param string|array|\Traversable	$files		The file(s)/directorie(s) to change group
	 * @param string					$user		The owner user name
	 * @param bool 						$recursive	Whether change the owner recursively or not
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception	the filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function chown($files, $user, $recursive = false);

	/**
	 * Eliminates useless . and .. components from specified path.
	 *
	 * @param string $path Path to clean
	 *
	 * @return string Cleaned path
	 */
	public function clean_path($path);

	/**
	 * Copies a file.
	 *
	 * This method only copies the file if the origin file is newer than the target file.
	 *
	 * By default, if the target already exists, it is not overridden.
	 *
	 * @param string	$origin_file	The original filename
	 * @param string	$target_file	The target filename
	 * @param bool		$override		Whether to override an existing file or not
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied
	 */
	public function copy($origin_file, $target_file, $override = false);

	/**
	 * Atomically dumps content into a file.
	 *
	 * @param string	$filename	The file to be written to.
	 * @param string	$content	The data to write into the file.
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be written
	 */
	public function dump_file($filename, $content);

	/**
	 * Checks the existence of files or directories.
	 *
	 * @param string|array|\Traversable	$files	files/directories to check
	 *
	 * @return bool	Returns true if all files/directories exist, false otherwise
	 */
	public function exists($files);

	/**
	 * Checks if a path is absolute or not
	 *
	 * @param string	$path	Path to check
	 *
	 * @return	bool	true if the path is absolute, false otherwise
	 */
	public function is_absolute_path($path);

	/**
	 * Checks if files/directories are readable
	 *
	 * @param string|array|\Traversable	$files		files/directories to check
	 * @param bool						$recursive	Whether or not directories should be checked recursively
	 *
	 * @return bool True when the files/directories are readable, otherwise false.
	 */
	public function is_readable($files, $recursive = false);

	/**
	 * Test if a file/directory is writable
	 *
	 * @param string|array|\Traversable	$files		files/directories to perform write test on
	 * @param bool						$recursive	Whether or not directories should be checked recursively
	 *
	 * @return bool True when the files/directories are writable, otherwise false.
	 */
	public function is_writable($files, $recursive = false);

	/**
	 * Given an existing path, convert it to a path relative to a given starting path
	 *
	 * @param string $end_path		Absolute path of target
	 * @param string $start_path	Absolute path where traversal begins
	 *
	 * @return string Path of target relative to starting path
	 */
	public function make_path_relative($end_path, $start_path);

	/**
	 * Mirrors a directory to another.
	 *
	 * @param string		$origin_dir	The origin directory
	 * @param string		$target_dir	The target directory
	 * @param \Traversable	$iterator	A Traversable instance
	 * @param array			$options	An array of boolean options
	 *									Valid options are:
	 *										- $options['override'] Whether to override an existing file on copy or not (see copy())
	 *										- $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink())
	 *										- $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied.
	 * 															The filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function mirror($origin_dir, $target_dir, \Traversable $iterator = null, $options = array());

	/**
	 * Creates a directory recursively.
	 *
	 * @param string|array|\Traversable	$dirs	The directory path
	 * @param int						$mode	The directory mode
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception On any directory creation failure
	 * 															The filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function mkdir($dirs, $mode = 0777);

	/**
	 * Global function for chmodding directories and files for internal use
	 *
	 * This function determines owner and group whom the file belongs to and user and group of PHP and then set safest possible file permissions.
	 * The function determines owner and group from common.php file and sets the same to the provided file.
	 * The function uses bit fields to build the permissions.
	 * The function sets the appropiate execute bit on directories.
	 *
	 * Supported constants representing bit fields are:
	 *
	 * filesystem_interface::CHMOD_ALL - all permissions (7)
	 * filesystem_interface::CHMOD_READ - read permission (4)
	 * filesystem_interface::CHMOD_WRITE - write permission (2)
	 * filesystem_interface::CHMOD_EXECUTE - execute permission (1)
	 *
	 * 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.
	 *
	 * @param string|array|\Traversable	$file				The file/directory to be chmodded
	 * @param int						$perms				Permissions to set
	 * @param bool						$recursive			If the permissions should be changed recursively
	 * @param bool						$force_chmod_link	Try to apply permissions to symlinks as well
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception	the filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function phpbb_chmod($file, $perms = null, $recursive = false, $force_chmod_link = false);

	/**
	 * A wrapper for PHP's realpath
	 *
	 * Try to resolve realpath when PHP's realpath is not available, or
	 * known to be buggy.
	 *
	 * @param string	$path	Path to resolve
	 *
	 * @return string	Resolved path
	 */
	public function realpath($path);

	/**
	 * Removes files or directories.
	 *
	 * @param string|array|\Traversable	$files	A filename, an array of files, or a \Traversable instance to remove
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception When removal fails.
	 * 															The filename which triggered the error can be
	 * 															retrieved by filesystem_exception::get_filename()
	 */
	public function remove($files);

	/**
	 * Renames a file or a directory.
	 *
	 * @param string	$origin		The origin filename or directory
	 * @param string	$target		The new filename or directory
	 * @param bool		$overwrite	Whether to overwrite the target if it already exists
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception	When target file or directory already exists,
	 * 															or origin cannot be renamed.
	 */
	public function rename($origin, $target, $overwrite = false);

	/**
	 * Creates a symbolic link or copy a directory.
	 *
	 * @param string	$origin_dir			The origin directory path
	 * @param string	$target_dir			The symbolic link name
	 * @param bool		$copy_on_windows	Whether to copy files if on Windows
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception When symlink fails
	 */
	public function symlink($origin_dir, $target_dir, $copy_on_windows = false);

	/**
	 * Sets access and modification time of file.
	 *
	 * @param string|array|\Traversable	$files			A filename, an array of files, or a \Traversable instance to create
	 * @param int						$time			The touch time as a Unix timestamp
	 * @param int						$access_time	The access time as a Unix timestamp
	 *
	 * @throws \phpbb\filesystem\exception\filesystem_exception	When touch fails
	 */
	public function touch($files, $time = null, $access_time = null);
}