| core_file

# Class: Bs_FileSystem Source Location: /core/file/Bs_FileSystem.class.php
### Class Overview
    Bs_Object
       |
       --Bs_FileSystem
FileSystem Basic filesystem class. gets extended by Bs_File and Bs_Dir. #### Author(s): andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org> #### Version: 4.5.$Revision: 1.4 $ $Date: 2003/10/29 17:48:37 $ #### Copyright: blueshoes.org | ### Variables $_Bs_System $_lastFetchedFileAttr | ### Methods Bs_FileSystem basename getCwd getFileAttr getFileExtension getFileName getFullPath getPathStem getRealPath getRealPathSplit getWithoutFileExtension isLink isValidFilename isValidFullPath isValidPath makeValidFileName realPath realPathSplit setFullPath standardizePath
### Child classes: Bs_Dir Directory Class. Bs_File * Represents a FILE (or a DIRECTORY?) as an Object | ### Inherited Variables | ### Inherited Methods #### 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 93] FileSystem Basic filesystem class. gets extended by Bs_File and Bs_Dir. Based on this object we have a dir and file object:
                           FileSystem
                               |
                         +-----+-------+
                        Dir          File
NOTE: The path format for input may be windows-like with '\' backslashes. (Even some PHP functions spit out that fomat on Winblows). BUT in all output we use iX path format with '/' forslash. Luckelly Winblows has no problem with this format. Main concept change ! This class will have no knowlege of a dir-possition given by paramters. It's an attribute for the Dir- and File-class. In this way all routines can be looked as static. --sam 7.6.2001 not all methods. for example not getFileAttr() because of $this->_lastFetchedPath we'd need to work around that. 2001/10/04 --andrej In reality, a dir is not much different from a file. Actually on unix a dir *is* a file. But because you usually do different stuff with them (files -> read|write) and directories can 'hold' subdirs and files, we separate them. So wath do Dir and File have in commen?
                               iX (Unix) | Windows NT
     o Methods:
                move                X    |    X
                delete              X    |    X
                rename              X    |    X
     o Touch:
                create time         X    |    X
                access time         X    |    X        // If it's a dir == create time
                modify time         X    |    X        // If it's a dir == create time
     o File Access:
                writeable           X    |    X
                readable            X    |    X
                executeable         X    |    ? 1*)
                hidden, archive     -    |    X       // We will ignor this ones
     o File Rights
                owner               X    |    ? 2*)
                group               X    |    ? 2*)
                all                 X    |    ? 2*)
     o Ownership
                owner               X    |    ? 3*)
                group               X    |    ? 3*)
     o Linking
                hard/soft link      X    |    - 4*)
                short cut           - 4*)|    X

       1*) How does windows react? TRUE if readable? dser
       2*) Windows hat directory sharing. Is that what we see? What about files?
       3*) How does windows react? Who's the owner?
       4*) A 'short cut' is normal files (like a batch file) and *NOT* a link!
           Ever looked at a 'short cut' in the Windows-'Command Promt' (DOS-window)?
           It's just a stupid normal file that ends with ".lnk". Any file ending with ".lnk"
           is look as a 'short cut' to Windows.
           Lets say we have a the 'short cut' foo.lnk that 'links' to a text file foo.txt.
           Now wath would you expect when you type:
              more foo.lnk
           If it were a link you would expect the content of foo.txt. But *suprise* you'll get
           a dump of the binary foo.lnk file. *brrrr*
           It's realy stupid and cheap! I did it 10 years ago by writing a normal ".bat"-file (batch files)
           that switched to the right dir and called that program. The difference is that 'short cut'-files
           are binary and therefore not editable in a text editor.
           That's way you only can have a 'short cut' to files (no dirs).
MEMO: Lots of problems with php's filesystem functions when we're on a winblows box :( 1) many methods just don't work - as the docu says 2) many bugs listed at php.net dependencies: Bs_System, Bs_String #### Tags:
version: | 4.5.$Revision: 1.4 $ $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 #### $_Bs_System = [line 100] pseudostatic instance of Bs_System.
Type: | object _Bs_System
[ Top ] #### $_lastFetchedFileAttr = array() [line 117]
Type: | mixed
[ Top ] ### Class Methods ### constructor Bs_FileSystem [line 123]
`Bs_FileSystem Bs_FileSystem( )`
* Constructor. [ Top ] ### method basename [line 575]
`string basename( string $path)`
returns the base name of a path (filename). replacement to php's basename() function which sucks because dirs do not end with '/' and some other stuff I don't recall. The path you give is first standardized replace '\' with '/' see http://www.php.net/manual/en/function.basename.php #### Parameters:
string | $path |
[ Top ] ### method getCwd [line 220]
`string getCwd( )`
Gets the current process working directory by using PHP's getcwd() and converting the result to our standard. #### Tags:
return: | A path to the current working directory of the current process.
[ Top ] ### method getFileAttr [line 147]
`hash getFileAttr( [string $path = ''], [boolean $clearCache = FALSE])`
Return most of the file attribute info. (Should work with Windows too). this function only gets called from NOTE: Invoking the stat or lstat system call on most systems is quite expensive. Therefore, the result of the last call to many of the status functions in PHP are stored for use on the next such call using the same file/dir-name. If you wish to force a new status check, for instance if the file is being checked many times and may change or disappear, set the param '$clearCache' to TRUE to force a system reread. !!!This value is only cached for the lifetime of a single request.!!! #### Tags:
return: | If file exists: A hash with the attributes of the '$path'.
throws: | FALSE if file does not exist
access: | public
see: | PHP function clearstatcache();
#### Parameters:
string | $path |
boolean | $clearCache | see note above
[ Top ] ### method getFileExtension [line 519]
`string getFileExtension( [string $fullPath = NULL])`
Get the file extension from a path. examples: 'c:\myFile.php' -> 'php' 'c:\myFile.class.PHP' -> 'PHP' 'c:\myFile' -> '' 'c:\myFile.class.php.lnk' -> 'php' <= special case on winblows for links may be used without param, then it will be for the file/dir that is currently in use. otherwise it is used pseudostatic. the extension is NOT converted to lower case! #### Tags:
return: | the file extension
see: | $this->getWithoutFileExtension()
#### Parameters:
string | $fullPath | (a path to a dir or file on that machine)
[ Top ] ### method getFileName [line 589]
`void getFileName( mixed $path)`
#### Tags:
deprecated: | as of bs4.3, use $this->basename() instead. this here makes no sense, it's just a different name.
[ Top ] ### method getFullPath [line 464]
`string getFullPath( )`
returns the directory or file that this object (subclassed file or dir object) is looking at. #### Tags:
access: | public
[ Top ] ### method getPathStem [line 490]
`string getPathStem( string $path)`
Get the stem part of a path. Examples on Windows: (on *nix there is of course no drive prefix 'f:') "f:/dir 790/asdf/file.xyz.html" => "f:/dir 790/asdf/" "f:\\dir 790\\asdf\\file.xyz.html" => "f:/dir 790/asdf/" "f:\\dir 790\\asdf/" => "f:/dir 790/asdf/" "f:\\dir 790\\asdf" => "f:/dir 790/" <= even if asdf is a dir!! (see note II) NOTE I: PHP's dirname() doesn't return the trailing slash, but we do. NOTE II: This method doesn't try to check if the last part is a file or a dir, when the trailing slash is not given. because the fullPath given doesn't need to exist (on this system)... so even if in 'c:/one/two' two is a directory, only 'c:/one/' will be returned. #### Tags:
return: | the path (without filename)
throws: | false
#### Parameters:
string | $path | a path
[ Top ] ### method getRealPath [line 245]
`string getRealPath( [string $path = ''])`
Returns canonicalized real pathname *with* ending '/' if it's a dir AND(!) checks for existence! This method basically executes our Bs_FileSystem::getRealPathSplit() function and checks for file existence. Make On windows, something like 'c:/dir////dir2' is converted to 'c:\dir\dir2', but i want to have it converted to 'c:/dir/dir2/'. I like to have foreslashes on all systems. And in this case, dir2 was a directory even if the trailing slash was missing. realPath() should come with the intelligence to add it if dir2 is not a file, imo. #### Tags:
return: | the real path
throws: | bool FALSE if the path does not exist
see: | Bs_FileSystem::realPathSplit()
see: | Bs_FileSystem::realPath()
see: | Bs_FileSystem::getRealPathSplit()
#### Parameters:
string | $path | a path or a part of it
[ Top ] ### method getRealPathSplit [line 314]
`hash getRealPathSplit( [string $path = ''])`
Returns a splited canonicalized real pathname *with* ending '/' if it's a dir. AND(!) checks for existence! This method basically executes our Bs_FileSystem::getRealPathSplit() function and checks for file existens. returns a hash: ['pathRoot'] <- Things like '/', 'c:/', 'http://', 'ftp://' ['pathCore'] <- e.g. 'path/to/a/subdir/' ['file'] <- if a file was in the path find it here ['tailDir'] <- for convinience the last dir of the ['pathCore'] e.g. 'subdir' ['realPath'] <- for convinience ['pathRoot'] . ['pathCore'] . ['file']; #### Tags:
return: | see text above
throws: | bool FALSE if the path does not exist
see: | Bs_FileSystem::realPathSplit()
see: | Bs_FileSystem::realPath()
see: | Bs_FileSystem::getRealPath()
static: |
#### Parameters:
string | $path | a path or a part of it
[ Top ] ### method getWithoutFileExtension [line 550]
`string getWithoutFileExtension( [string $fullPath = NULL])`
returns the filename without the file extension. examples: 'myFile.php' -> 'myFile' 'myFile.class.php' -> 'myFile.class' 'myFile' -> 'myFile' 'c:\myFile.gif' -> 'myFile' 'c:\myFile.class.php.lnk' -> 'myFile.class' <= special case on winblows for links #### Tags:
return: | (file name (or path) without file extension.)
since: | bs4.4
see: | $this->getFileExtension()
#### Parameters:
string | $fullPath | (a path to a dir or file on that machine)
[ Top ] ### method isLink [line 697]
`bool isLink( [string $fullPath = null])`
tells wheter the current file/path (or $fullPath) is a link or not. uses php's is_link() on *nix and something handmade on winblows. may be used without param, then it will be for the file/dir that is currently in use. otherwise it is used pseudostatic. #### Parameters:
string | $fullPath | (a path to a dir or file on that machine)
[ Top ] ### method isValidFilename [line 609]
`void isValidFilename( mixed $fileName, [mixed $os = 'all'])`
windows filename and dirname (tested on winnt 4.0 german) 1) cannot have one of these characters: \ / : * ? " < > | 2) cannot start or end with a space 3) cannot start with a dot '.' if you want to test with a scary filename, use this one (on windows): {}d % test.txt {} _-d°§+@ #ç&()=~^`´'$£ no file can be named '.' or '..' (which could cause bugs with these unix-like things). linux filename 1) cannot have one of these characters: & 2) some more, don't know. #### Tags:
see: | Bs_FileSystem::makeValidFileName()
todo: | all
[ Top ] ### method isValidFullPath [line 681]
`void isValidFullPath( mixed $fullPath, [mixed $system = NULL])`
#### Tags:
todo: | all
[ Top ] ### method isValidPath [line 674]
`void isValidPath( mixed $path, [mixed $system = NULL])`
#### Tags:
todo: | all
[ Top ] ### method makeValidFileName [line 638]
`string makeValidFileName( string $fileName, [string $os = 'all'])`
removes/replaces invalid characters in the filename specified. param $os: i recommend you use the default, 'all'. all => the returned file name will be usable on all systems. the behavior is the same as for 'linux'. win => remove these chars: \ / : * ? " < > | may have spaces, but may not start or end with one. will be cut. linux => remove all chars that are not a-zA-Z 0-9 _ . (underscore and dot) spaces are replaced with an underscore. SPACES AND/OR UNDERSCORES THAT ARE TOGETHER WILL BE CUT DOWN TO ONE! examples: "foo__" => "foo_" //2 underscores become one underscore "f oo__" => "f_oo_" //2 spaces become one underscore "f _ oo" => "f_oo" //space, underscore, space becomes one underscore altough windows does not always like it, a dot at the beginning is left as is. #### Tags:
return: | (the clean file name)
see: | Bs_FileSystem::isValidFilename()
since: | bs4.5
#### Parameters:
string | $fileName |
string | $os | (one of: 'all' (default), 'win', 'linux')
[ Top ] ### method realPath [line 285]
`string realPath( string $path)`
Returns canonicalized real pathname *with* ending '/' if it's a dir. No existence check! Replacement for php's realpath(). CAUTION: for the built in php function realpath(): Use this method (and php's realpath()) only with a path that exists on your current system!!! Otherwise you might get wrong results, the behavior is varying from returning an empty string to wrong paths. Resolves references to './', '/./', '/../' and extra '/' characters in the input path and returns the canonicalized absolute pathname. The resulting path will *not* have './', '/./' or '/../' components. NOTE 1: No file systems checks are made! So path may or *may not* exsist! See Bs_FileSystem::getRealPath() NOTE 2: Accespts *fore*- and *back*-slashes E.g. '/aa/bb\\cc\\dd/' NOTE 3: Special 'Path prefixes' are preserved E.g. if input path starts with '//' (network path incl stuff like ftp:// http://) '/' (absolute path) 'x:/' (Winblos drive letter *yuck*) BUT './' (relative path) is stripped ! E.g. ./aaa/bbb/ -> aaa/bbb/ The resulting path will have the same prefix. NOTE 4: If path does *not* end with a '/', it is considerd to be a *path and file* and it therefore the file will always suffix of the resulting path. #### Tags:
return: | the canonicalized real pathname *with* ending '/' if it's a dir.
see: | Bs_FileSystem::realPathSplit()
see: | Bs_FileSystem::realPath()
see: | Bs_FileSystem::getRealPath()
static: |
#### Parameters:
string | $path | a path or a part of it
[ Top ] ### method realPathSplit [line 351]
`hash realPathSplit( string $path)`
Returns a splited canonicalized real pathname *with* ending '/' if it's a dir. No existence check! NOTE 1: No file systems checks are made! So path may or *may not* exsist! See Bs_FileSystem::getRealPathSplit() returns a hash: ['pathRoot'] <- Things like '/', 'c:/', 'http://', 'ftp://' ['pathCore'] <- e.g. 'path/to/a/subdir/' ['file'] <- if a file was in the path find it here ['tailDir'] <- for convinience the last dir of the ['pathCore'] e.g. 'subdir' ['realPath'] <- for convinience ['pathRoot'] . ['pathCore'] . ['file']; #### Tags:
return: | see text above
see: | Bs_FileSystem::realPath()
see: | Bs_FileSystem::getRealPathSplit()
see: | Bs_FileSystem::getRealPath()
static: |
#### Parameters:
string | $path | a path or a part of it
[ Top ] ### method setFullPath [line 442]
`bool setFullPath( string $workingDir)`
Set our view to the directory or file passed by '$workingDir'. #### Tags:
return: | TRUE if it's a new and valid dir, FALSE if it did not change.
access: | public
Overridden in child classes as: Bs_Dir::setFullPath() Set our view to the directory passed by '$workingDir'. #### Parameters:
string | $workingDir | a path
[ Top ] ### method standardizePath [line 208]
`string standardizePath( string $path)`
The path format for input may be windows-like with '\' backslashes. (Even some PHP functions spit out that fomat on Winblows). BUT in all output we use iX path format with '/' forslash. Luckelly Winblows has no problem with this format. #### Tags:
return: | A stanadardized path with '/' instead of '\'
#### Parameters:
string | $path |
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:09:08 +0100 by phpDocumentor 1.2.3