mkungla / libhowi-filesystem

Commons/FilesystemInterface.inc

<?php
/********************************************************************
 * Created by:	Marko Kungla @ OkramLabs on Aug 6, 2012 - 9:58:05
 * Contact:		okramlabs@gmail.com - https://okramlabs.com
 * @copyright:	2015 OkramLabs - https://okramlabs.com
 * @license		MIT
 *
 * Package name:libhowi-filesystem
 * @category	HOWI3
 * @package		libhowi
 * @subpackage	filesystem
 *
 * Lang:		PHP
 * Encoding:	UTF-8
 * File:		FilesystemInterface.inc
 * @link		https://
 ********************************************************************
 * Contributors:
 * @author		Marko Kungla <okramlabs@gmail.com>
 *  	Github:	https://github.com/mkungla
 ********************************************************************
 * Comments:
 */
namespace HOWI3\libhowi\Filesystem\Commons;

interface FilesystemInterface
{

    /**
     * Construct with or without current working directory
     *
     * @param string $setCwd            

Should the type for parameter $setCwd not be false|string?

     */
    public function __construct($setCwd = false);

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * Creates Directory object with basename
     *
     * @param string $directory            

Should the type for parameter $directory not be false|string?

     * @param string $dirname            

Should the type for parameter $dirname not be false|string?

     * @param bool $recursive            
     * @param int $mode            

Should the type for parameter $mode not be false|integer?

     * @param resource $context            

Should the type for parameter $context not be false|resource?

     *
     * @return object DirectoryPlaceholderObject | DirectoryTreeObject
     */
    public function dir($directory = false, $dirname = false, $recursive = true, $mode = false, $context = false);

    /**
     * Creates FileObject object with basename
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @param string $dirname            

Should the type for parameter $dirname not be false|string?

     * @param mixed $data            
     * @param int $flags            
     * @param resource $context            

Should the type for parameter $context not be resource|null?

     */
    public function file($filename = false, $dirname = false, $data = '', $flags = 0, $context = null);

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * Creates InfoObject object
     *
     * @param string $basename            

Should the type for parameter $basename not be false|string?

     * @param string $directory            

Should the type for parameter $directory not be false|string?

     */
    public function infoObject($basename = false, $directory = false);

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * Creates TmpObject object with keyword
     *
     * @param string $keyword            
     */
    public function tmp($keyword = 'tmp');

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * Creates LinkObject object with keyword
     *
     * @param string $keyword            
     */
    public function link($keyword = 'link');

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * Change current working directory.
     *
     * Rreturn true if chnging working dir is success.
     * Returns false if directory does not exist or can not be read
     *
     * @param string $path            

Should the type for parameter $path not be false|string?

     * @param string $validate_dir_name

Should the type for parameter $validate_dir_name not be false|string?

     *            base name of the directory
     *            useful when navigating ../../ and you want to make sure
     *            you are on directore named "$validate_dir_name"
     *            
     * @return bool
     */
    public function cd($path = false, $validate_dir_name = false);

    /**
     * Delete remove directories or files
     *
     * When shred is true then files will be destroyed by shred command before remove
     *
     * @param unknown $pathname            
     * @param string $shred            

Should the type for parameter $shred not be false|string?

     */
    public function rm($pathname, $shred = false);

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * List files and directories inside the specified path
     *
     * @param string $path            

Should the type for parameter $path not be false|string?

     * @return array
     */
    public function scandir($path = false);

    /**
     * Gives information about a file or directory
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @return array
     */
    public function stat($filename = false);

    /**
     * getDiskTotalSpace
     *
     * Given a string containing a directory, this function will return the total
     * number of bytes on the corresponding filesystem or disk partition.
     *
     * @param string $partition_location            

Should the type for parameter $partition_location not be false|string?

     * @param string $convert            

Should the type for parameter $convert not be false|string?

     * @return number of bytes or formated output if $convert is not false
     */
    public function getDiskTotalSpace($partition_location = false, $convert = false);

    /**
     * * Given a string containing a directory, this function will return the number
     * of bytes available on the corresponding filesystem or disk partition.
     *
     * @param string $partition_location            

Should the type for parameter $partition_location not be false|string?

     * @param string $convert            

Should the type for parameter $convert not be false|string?

     * @return number of bytes or formated output if $convert is not false
     */
    public function getDiskFreeSpace($partition_location = false, $convert = false);

    /**
     * Attempts to change the group of the file filename to group.
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @param string $group            

Should the type for parameter $group not be false|string?

     * @return bool
     */
    public function chgrp($filename = false, $group = false);

    /**
     * Attempts to change the mode of the specified file to that given in mode.
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @param string $mode            

Should the type for parameter $mode not be false|string?

     * @return bool
     */
    public function chmod($filename = false, $mode = false);

    /**
     * Attempts to change the owner of the file filename to user user.
     * Only the superuser may change the owner of a file.
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @param string $user            

Should the type for parameter $user not be false|string?

     */
    public function chown($filename = false, $user = false);

For interfaces and abstract methods it is generally a good practice to add a @return annotation even if it is just @return void or @return null, so that implementors know what to do in the overridden method.

    /**
     * clearstatcache — Clears file status cache
     * When you use stat(), lstat(), or any of the other functions listed in the affected
     * functions list (below), PHP caches the information those functions return in order to
     * provide faster performance.
     * However, in certain cases, you may want to clear the cached information
     * for instance you write some file and whant to read any stats after you should run
     * $FS->clearstatcache(false,$filename);
     *
     * @return void
     */
    public function clearstatcache($clear_realpath_cache = false, $filename = false);

    /**
     * Copies file or directory with all the contents to new location
     * bit similar as 'cp -R'
     * Makes a copy of the file source to dest.
     *
     * @param string $source            

Should the type for parameter $source not be false|string?

     * @param string $dest            

Should the type for parameter $dest not be false|string?

     * @param string $context            

Should the type for parameter $context not be false|string?

     * @return bool
     */
    public function copy($source = false, $dest = false, $context = false);

    /**
     * Renames (move) a file or entire directory
     *
     * @param string $oldname            

Should the type for parameter $oldname not be false|string?

     * @param string $newname            

Should the type for parameter $newname not be false|string?

     * @param string $context            

Should the type for parameter $context not be false|string?

     * @return bool
     */
    public function mv($oldname = false, $newname = false, $context = false);

    /**
     * Match filename against a pattern
     * FNM_NOESCAPE Disable backslash escaping.
     * FNM_PATHNAME Slash in string only matches slash in the given pattern.
     * FNM_PERIOD Leading period in string must be exactly matched by period in the given pattern.
     * FNM_CASEFOLD Caseless match. Part of the GNU extension.
     *
     * @param string $pattern            

Should the type for parameter $pattern not be false|string?

Should the type for parameter $string not be false|string?

     * @param string $string            
     * @param string $flags            

Should the type for parameter $flags not be false|string?

     *
     * @return bool
     */
    public function namePatternMatch($pattern = false, $string = false, $flags = false);

    /**
     * Find pathnames matching a pattern
     *
     * The getGlob() function searches for all the pathnames matching pattern
     * according to the rules used by the libc glob() function,
     * which is similar to the rules used by common shells.
     *
     * @param string $pattern            

Should the type for parameter $pattern not be false|string?

     * @param number $flags            

Consider making the type for parameter $flags a bit more specific; maybe use integer.

     * @return array matching paths
     */
    public function getGlob($pattern = false, $flags = 0);

    /**
     * Tells whether the file was uploaded via HTTP POST
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @return bool
     */
    public function isUploadedFile($filename = false);

    /**
     * Get realpath cache entries
     *
     * @return array
     */
    public function getRealpathCache();

    /**
     * Get realpath cache size
     *
     * @return int
     */
    public function getRealpathCacheSize();

    /**
     * Closes DirectoryTreeObject or FileObjects for given basename
     *
     * While FileObjects are closed anyway automatically when FS gets destructed
     * but you might close the file your self. For inctance when multithreading / tasking
     *  
     * @param string $keyword

Should the type for parameter $keyword not be false|string?

     * @return bool true|false
     */
    public function close($keyword = false);

    /**
     * Sets access and modification time of the item
     *
     * @param string $filename            

Should the type for parameter $filename not be false|string?

     * @param string $time            

Should the type for parameter $time not be false|string?

     * @param string $atime            

Should the type for parameter $atime not be false|string?

     * @return bool
     */
    public function touch($filename = false, $time = false, $atime = false);

    /**
     * Returns all loaded directory keys
     *
     * @return array
     */
    public function getDirKeys();
    
    /**
     * Returns all loaded file keys
     *
     * @return array
     */
    public function getFileKeys();
    
    /**
     * Create a directory and file structure from custom array or
     * Make structure from DirectoryObject::lsTree output
     * If there happens to be collision between array so dir or file already exists
     * then it will be simply skipped. Directory must be a key and always habe array as value
     * even when directory is empty. Files have to have key regular int and value "string" 
     * filename 
     * 
     * @param string $rootpath atleast rootpath parent directory must exist! 
     * @param array $data_array 
     * @return bool true on success fase on failure
     */
    public function createStructure($rootpath,$data_array);
}