<?php
namespace Kant\Filesystem\Contracts;

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 \Kant\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);
}
