<?php namespace Illuminate\Contracts\Filesystem;

interface Filesystem {

	/**
	 * The public visibility setting.
	 *
	 * @var string
	 */
	const VISIBILITY_PUBLIC = 'public';

	/**
	 * The private visibility setting.
	 *
	 * @var string
	 */
	const VISIBILITY_PRIVATE = 'private';

	/**
	 * Determine if a file exists.
	 *
	 * @param  string  $path
	 * @return bool
	 */
	public function exists($path);

	/**
	 * Get the contents of a file.
	 *
	 * @param  string  $path
	 * @return string
	 *
	 * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
	 */
	public function get($path);

	/**
	 * Write the contents of a file.
	 *
	 * @param  string  $path
	 * @param  string|resource  $contents
	 * @param  string  $visibility
	 * @return bool
	 */
	public function put($path, $contents, $visibility = null);

	/**
	 * Get the visibility for the given path.
	 *
	 * @param  string  $path
	 * @return string
	 */
	public function getVisibility($path);

	/**
	 * Set the visibility for the given path.
	 *
	 * @param  string  $path
	 * @param  string  $visibility
	 * @return void
	 */
	public function setVisibility($path, $visibility);

	/**
	 * Prepend to a file.
	 *
	 * @param  string  $path
	 * @param  string  $data
	 * @return int
	 */
	public function prepend($path, $data);

	/**
	 * Append to a file.
	 *
	 * @param  string  $path
	 * @param  string  $data
	 * @return int
	 */
	public function append($path, $data);

	/**
	 * Delete the file at a given path.
	 *
	 * @param  string|array  $paths
	 * @return bool
	 */
	public function delete($paths);

	/**
	 * Copy a file to a new location.
	 *
	 * @param  string  $from
	 * @param  string  $to
	 * @return bool
	 */
	public function copy($from, $to);

	/**
	 * Move a file to a new location.
	 *
	 * @param  string  $from
	 * @param  string  $to
	 * @return bool
	 */
	public function move($from, $to);

	/**
	 * Get the file size of a given file.
	 *
	 * @param  string  $path
	 * @return int
	 */
	public function size($path);

	/**
	 * Get the file's last modification time.
	 *
	 * @param  string  $path
	 * @return int
	 */
	public function lastModified($path);

	/**
	 * Get an array of all files in a directory.
	 *
	 * @param  string|null  $directory
	 * @param  bool  $recursive
	 * @return array
	 */
	public function files($directory = null, $recursive = false);

	/**
	 * Get all of the files from the given directory (recursive).
	 *
	 * @param  string|null  $directory
	 * @return array
	 */
	public function allFiles($directory = null);

	/**
	 * Get all of the directories within a given directory.
	 *
	 * @param  string|null  $directory
	 * @param  bool  $recursive
	 * @return array
	 */
	public function directories($directory = null, $recursive = false);

	/**
	 * Get all (recursive) of the directories within a given directory.
	 *
	 * @param  string|null  $directory
	 * @return array
	 */
	public function allDirectories($directory = null);

	/**
	 * Create a directory.
	 *
	 * @param  string  $path
	 * @return bool
	 */
	public function makeDirectory($path);

	/**
	 * Recursively delete a directory.
	 *
	 * @param  string  $directory
	 * @return bool
	 */
	public function deleteDirectory($directory);

}
