| core_file

# Class: Bs_Dir Source Location: /core/file/Bs_Dir.class.php
### Class Overview
    Bs_Object
       |
       --Bs_FileSystem
          |
          --Bs_Dir
Directory Class. #### Author(s): andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org> #### Version: 4.3.$Revision: 1.2 $ $Date: 2003/10/29 17:48:37 $ #### Copyright: blueshoes.org | ### Variables $_dirObj | ### Methods Bs_Dir clearCache cp cpDir create destruct emptyDir getFileList getFreeDiskSpace isEmpty mkpath mv rm search searchAndReplace setFullPath
### Inherited Variables #### Class: Bs_FileSystem Bs_FileSystem::$_Bs_System Bs_FileSystem::$_lastFetchedFileAttr | ### Inherited Methods #### Class: Bs_FileSystem Bs_FileSystem::Bs_FileSystem() * Constructor. Bs_FileSystem::basename() returns the base name of a path (filename). Bs_FileSystem::getCwd() Gets the current process working directory by using PHP's getcwd() and converting the result to our standard. Bs_FileSystem::getFileAttr() Return most of the file attribute info. (Should work with Windows too). Bs_FileSystem::getFileExtension() Get the file extension from a path. Bs_FileSystem::getFileName() Bs_FileSystem::getFullPath() returns the directory or file that this object (subclassed file or dir object) is looking at. Bs_FileSystem::getPathStem() Get the stem part of a path. Bs_FileSystem::getRealPath() Returns canonicalized real pathname *with* ending '/' if it's a dir AND(!) checks for existence! Bs_FileSystem::getRealPathSplit() Returns a splited canonicalized real pathname *with* ending '/' if it's a dir. Bs_FileSystem::getWithoutFileExtension() returns the filename without the file extension. Bs_FileSystem::isLink() tells wheter the current file/path (or $fullPath) is a link or not. Bs_FileSystem::isValidFilename() windows filename and dirname (tested on winnt 4.0 german) Bs_FileSystem::isValidFullPath() Bs_FileSystem::isValidPath() Bs_FileSystem::makeValidFileName() removes/replaces invalid characters in the filename specified. Bs_FileSystem::realPath() Returns canonicalized real pathname *with* ending '/' if it's a dir. Bs_FileSystem::realPathSplit() Returns a splited canonicalized real pathname *with* ending '/' if it's a dir. Bs_FileSystem::setFullPath() Set our view to the directory or file passed by '$workingDir'. Bs_FileSystem::standardizePath() The path format for input may be windows-like with '\' backslashes. #### Class: Bs_Object Bs_Object::Bs_Object() Bs_Object::getErrors() Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack. Bs_Object::getLastError() Basic error handling: Get last error string from the global Bs_Error-error stack. Bs_Object::getLastErrors() Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors(). Bs_Object::persist() Persists this object by serializing it and saving it to a file with unique name. Bs_Object::setError() Basic error handling: Push an error string on the global Bs_Error-error stack. Bs_Object::toHtml() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::toString() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::unpersist() Fetches an object that was persisted with persist()
### Class Details [line 23] Directory Class. dependencies: bs_filesystem, bs_file (may be used for returning in getFileList()) #### Tags:
version: | 4.3.$Revision: 1.2 $ $Date: 2003/10/29 17:48:37 $
copyright: | blueshoes.org
author: | andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>
[ Top ] ### Class Variables #### $_dirObj = [line 29] PHP's pseudo-Directory-Object used to scan the file system.
Type: | mixed
[ Top ] ### Class Methods ### constructor Bs_Dir [line 41]
`Bs_Dir Bs_Dir( [$fullpath $workingDir = NULL])`
* Constructor. NOTE: Fullpath may be of any format. E.g. dir, dir/, dir/file, ./dir/dir/file, /dir ... crap is: if setFullPath in here fails, then you won't know. so if you want to be sure then you better call the constructor without params and then do setFullPath() yourself. #### Parameters:
$fullpath | $workingDir | string (default=""). The path to a file or dir.
[ Top ] ### method clearCache [line 485]
`void clearCache( )`
[ Top ] ### method cp [line 540]
`bool cp( string $oldname, string $newname)`
copies a file or directory. if it's a dir then $this->cpDir() will be called. the new location will have the same chmod. #### Tags:
since: | bs4.4
#### Parameters:
string | $oldname |
string | $newname |
[ Top ] ### method cpDir [line 563]
`bool cpDir( string $oldname, string $newname, [array $ignoreDirs = NULL], [bool $isWindows = NULL])`
copies a directory recursively. the new location will have the same chmod. #### Tags:
since: | bs4.4
#### Parameters:
string | $oldname |
string | $newname |
array | $ignoreDirs | (vector of dirs you want to ignore, eg 'CVS'. on windows it's compared case insensitive.)
bool | $isWindows | (if not specified then the method will find out itself. don't worry. used internally as cache.)
[ Top ] ### method create [line 522]
`void create( )`
[ Top ] ### method destruct [line 50]
`void destruct( )`
destructor. [ Top ] ### method emptyDir [line 452]
`bool emptyDir( [bool $recursive = FALSE], [string $regExp = NULL])`
removes files from the directory. keeps the directory. links won't be followed, but deleted. $Bs_Dir->emptyDir() will give the same result as "rm *" in linux. NOTE: this is NOT the same as $this->rm(). #### Tags:
return: | TRUE
see: | $this->rm()
todo: | remove empty subdirs afterwards? a prune() method would be neat (that dives into a dir and removes empty subdirs).
throws: | bs_exception
access: | public
#### Parameters:
bool | $recursive | (default is FALSE.)
string | $regExp | (if given then the files need to match (perl-style) regExp in order to be deleted.)
[ Top ] ### method getFileList [line 251]
`vector getFileList( [array $params = array()])`
Get a list of files and dirs. calls itself recursively. To set the start dir use the ['fullPath']. If omitted the start dir is the dir this object is currently pointing at. ( See $this->setFullPath() ) The other fields are all optional. See the defaults in the text below. example: $params = array( 'fullPath' => '/foo/bar/', 'regFunction' => 'preg_match', 'regEx' => '/\.class\.php$/', 'fileDirLink' => array('dir'=>FALSE), 'sort' => TRUE, 'returnType' => 'subdir/file', ); $dir =& new Bs_Dir(); $fileList = $dir->getFileList($params); #### Tags:
return: | (see returnType. may be empty if nothing was found.)
throws: | exception
#### Parameters:
array | $params | a hash than can have these elements: ----------------------------------------------------------------------------------------------------- ['fullPath'] => string Starting point. The absolute path. Default: $this->_fullPath If *NOT* set we take the fullPath of this object (if given). Otherwise we throw an exception. ----------------------------------------------------------------------------------------------------- ['regFunction'] => ('ereg'|'preg_match') Default: 'ereg'. You may set the PHP regex-function to use. Just pass function name as string. ----------------------------------------------------------------------------------------------------- ['regEx'] => regEx-string Default: ''; The regular expresion is matched with the found file names without path by default. If you want the path to be part of the match used the next param ['regWhere']. ----------------------------------------------------------------------------------------------------- ['regWhere'] => ('file'|'dir') Default: 'file'. See ['regEx'] above file = use reg expression on file only dir = use reg expression on whole path ----------------------------------------------------------------------------------------------------- ['depth'] => int Default: BS_DIR_UNLIM_DEPTH. How many directory levels the Dir should follow. = Do not follow any dir. (= Use only current dir given by the path). n = Go max n levels in depth. ----------------------------------------------------------------------------------------------------- ['fileDirLink'] => hash of flags. Default: all flags are set to TRUE ('file'=>TRUE, 'dir'=>TRUE, 'filelink'=>TRUE, 'dirlink'=>TRUE) Control if files and/or dirs are to be fetched. ! On iX mashines (NOT on Windows) you can also fetch file-LINKS and/or dir-LINKS. E.g. passing $params['fileDirLink'] = array('dir'=>FALSE) would ignore dirs (and leave the other settings as they are). ['fileDirLink']['file'] : real files ['fileDirLink']['dir'] : file links ['fileDirLink']['filelink'] : real dirs ['fileDirLink']['dirlink'] : dir links ----------------------------------------------------------------------------------------------------- ['followLinks'] => bool Default: FALSE (Only iX mashines NOT available on Windows) ----------------------------------------------------------------------------------------------------- ['sort'] => bool Default: FALSE Sort the files and dirs that are returnd. You may wish to turn this feature on but it will use CPU (Tested with 3000 files: With sort it's 4x slower) ----------------------------------------------------------------------------------------------------- ['returnType'] => ('fullpath'|'subpath'|'nested'|'nested2'|'fulldir/file'|'subdir/file'|'subdir/file2'|'object') Default: 'fullpath' Control how to format the return. Sample: /root ------ +-/subdir <--- starting Dir | + A.txt | + B.txt +--/emptydir NOTE: return order is system dependent!! DON'T look at order !! ['fullpath'] : return a vector filled with fullPath's + files e.g. [0] => '/root/subdir/A.txt' [1] => '/root/subdir/B.txt' [2] => '/root/subdir/emptydir/' ['subpath'] : return a vector filled with rel-paths (relative from the current path) to the files and dirs. [0] => 'A.txt' [1] => 'B.txt' [2] => 'emptydir/' ['nested'] : return a nested hash. the key is always the subpath, the value is false for files and a hash for dirs '/foo/A.txt' => FALSE '/foo/B.txt' => FALSE '/foo/emptydir' => array() ['nested2'] : return a nested hash. the key is numeric (à la vector) for files and string (dir name) for directories, the value is string (file name) for files, array for dirs (filled recursively). the array may be empty (if the dir found is empty). [0] => 'A.txt' [1] => 'B.txt' 'emptydir' => array() ['fulldir/file'] : return a vector filled with a 2-key hash : 'dir' and 'file' [0] => ('dir'=>'/root/subdir/', 'file'=>'A.txt') [1] => ('dir'=>'/root/subdir/', 'file'=>'B.txt') [2] => ('dir'=>'/root/subdir/emptydir/', 'file'=>'') ['subdir/file'] : return a vector filled with a 2-key hash : 'dir' and 'file' [0] => ('dir'=>'', 'file'=>'A.txt') [1] => ('dir'=>'', 'file'=>'B.txt') [2] => ('dir'=>'emptydir/', 'file'=>'') ['subdir/file2'] : return a vector filled with a 2-key hash : 'dir' and 'file' Same as ['subdir/file'] but when a dir is found, the last path part is stored in 'file' also. [0] => ('dir'=>'', 'file'=>'A.txt') [1] => ('dir'=>'', 'file'=>'B.txt') [2] => ('dir'=>'', 'file'=>'emptydir') ['object'] : return a vector holding objects of Bs_File and Bs_Dir [0] => new Bs_File('/root/subdir/A.txt') [1] => new Bs_File('/root/subdir/B.txt') [2] => new Bs_Dir('/root/subdir/emptydir/')
[ Top ] ### method getFreeDiskSpace [line 490]
`void getFreeDiskSpace( )`
[ Top ] ### method isEmpty [line 518]
`void isEmpty( )`
[ Top ] ### method mkpath [line 94]
`bool mkpath( string $path)`
creates the given path, not just the last directory. example: mkpath('c:/your/path/whatever'); even if c:\your already exists, but not path/whatever. you can use foreslashes or backslashes. got this from: http://www.php.net/manual/en/function.mkdir.php original name: ForceDirectories() gjukema@jukeware.com 22-Jan-2001 06:40 I needed a clean ForceDirectories function as used in Delphi. I grabbed the source and converted to PHP. Just pass in a $path like "/tmp/dir1/dir2", and all "/tmp/dir1/dir2" will be created if they don't exist - permissions allowed of coarse :). if the method fails, not everything (maybe parts) has been created. errors are suppressed. #### Tags:
return: | (TRUE on success, FALSE on failure.)
access: | public
#### Parameters:
string | $path |
[ Top ] ### method mv [line 520]
`void mv( )`
[ Top ] ### method rm [line 504]
`bool rm( [string $fullPath = NULL], [bool $recursive = TRUE])`
removes the directory. #### Tags:
return: | (TRUE on success, FALSE if it does not exist, is not a dir, or is not readable.)
see: | $this->emptyDir()
since: | bs4.4
#### Parameters:
string | $fullPath | (if not specified then the current one will be used.)
bool | $recursive | (remove everything recursively? default is TRUE.)
[ Top ] ### method search [line 525]
`void search( )`
[ Top ] ### method searchAndReplace [line 527]
`void searchAndReplace( )`
[ Top ] ### method setFullPath [line 64]
`bool setFullPath( string $workingDir)`
Set our view to the directory passed by '$workingDir'. If it's not the same dir as we were looking at before, free the resources and open a new view to the new dir. uses parent method. #### Tags:
access: | public
Overrides Bs_FileSystem::setFullPath() (Set our view to the directory or file passed by '$workingDir'.) #### Parameters:
string | $workingDir | a path
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:08:51 +0100 by phpDocumentor 1.2.3