phing-system-io

# Class: PhingFile Source Location: /system/io/PhingFile.php
### Class Overview
An abstract representation of file and directory pathnames. #### Author(s): #### Version: $Revision: 552 $ | ### Variables $pathSeparator $separator | ### Methods __construct canRead canWrite compareTo contents copyTo createNewFile createTempFile delete deleteOnExit equals exists getAbsoluteFile getAbsolutePath getCanonicalFile getCanonicalPath getLinkTarget getMode getName getParent getParentFile getPath getPrefixLength getTempDir getUser isAbsolute isDirectory isFile isHidden isLink lastModified length listDir listFiles listRoots mkdir mkdirs removeTempFile renameTo setLastModified setMode setReadOnly setUser toString toURI toURL _constructFileParentStringChild _constructPathname _constructStringParentStringChild _slashify __toString
### Class Details [line 31] An abstract representation of file and directory pathnames. #### Tags:
version: | $Revision: 552 $
[ Top ] ### Class Variables #### static $pathSeparator = [line 37] path separator string, static, obtained from FileSystem (; or :) #### Tags:
access: | public
Type: | mixed
[ Top ] #### static $separator = [line 34] separator string, static, obtained from FileSystem #### Tags:
access: | public
Type: | mixed
[ Top ] ### Class Methods ### constructor __construct [line 50]
`PhingFile __construct( [ $arg1 = null], [ $arg2 = null])`
constructor #### Parameters:
| $arg1 |
| $arg2 |
[ Top ] ### method canRead [line 365]
`true canRead( )`
Tests whether the application can read the file denoted by this abstract pathname. #### Tags:
return: | if and only if the file specified by this abstract pathname exists and can be read by the application; false otherwise
[ Top ] ### method canWrite [line 384]
`true canWrite( )`
Tests whether the application can modify to the file denoted by this abstract pathname. #### Tags:
return: | if and only if the file system actually contains a file denoted by this abstract pathname and the application is allowed to write to the file; false otherwise.
[ Top ] ### method compareTo [line 880]
`int compareTo( PhingFile $file)`
Compares two abstract pathnames lexicographically. The ordering defined by this method depends upon the underlying system. On UNIX systems, alphabetic case is significant in comparing pathnames; on Win32 systems it is not. #### Tags:
return: | Zero if the argument is equal to this abstract pathname, a value less than zero if this abstract pathname is lexicographically less than the argument, or a value greater than zero if this abstract pathname is lexicographically greater than the argument
#### Parameters:
PhingFile | $file | Th file whose pathname sould be compared to the pathname of this file.
[ Top ] ### method contents [line 527]
`string contents( )`
Convenience method for returning the contents of this file as a string. This method uses file_get_contents() to read file in an optimized way. #### Tags:
throws: | Exception - if file cannot be read
[ Top ] ### method copyTo [line 686]
`true copyTo( PhingFile $destFile)`
Simple-copies file denoted by this abstract pathname into another PhingFile #### Tags:
return: | if and only if the renaming succeeded; false otherwise
#### Parameters:
PhingFile | $destFile | The new abstract pathname for the named file
[ Top ] ### method createNewFile [line 548]
`true createNewFile( [ $parents = true], [ $mode = 0777])`
Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file. #### Tags:
return: | if the named file does not exist and was successfully created; false if the named file already exists
throws: | IOException if file can't be created
#### Parameters:
| $parents |
| $mode |
[ Top ] ### method createTempFile [line 835]
`void createTempFile( $prefix, $suffix, PhingFile $directory)`
Static method that creates a unique filename whose name begins with $prefix and ends with $suffix in the directory $directory. $directory is a reference to a PhingFile Object. Then, the file is locked for exclusive reading/writing. #### Tags:
author: | manuel holtgrewe, grin@gmx.net
throws: | IOException
access: | public
#### Parameters:
| $prefix |
| $suffix |
PhingFile | $directory |
[ Top ] ### method delete [line 561]
`true delete( )`
Deletes the file or directory denoted by this abstract pathname. If this pathname denotes a directory, then the directory must be empty in order to be deleted. #### Tags:
return: | if and only if the file or directory is successfully deleted; false otherwise
[ Top ] ### method deleteOnExit [line 579]
`void deleteOnExit( )`
Requests that the file or directory denoted by this abstract pathname be deleted when php terminates. Deletion will be attempted only for normal termination of php and if and if only Phing::shutdown() is called. Once deletion has been requested, it is not possible to cancel the request. This method should therefore be used with care. [ Top ] ### method equals [line 895]
`boolean equals( $obj)`
Tests this abstract pathname for equality with the given object. Returns true if and only if the argument is not null and is an abstract pathname that denotes the same file or directory as this abstract pathname. Whether or not two abstract pathnames are equal depends upon the underlying system. On UNIX systems, alphabetic case is significant in comparing pathnames; on Win32 systems it is not. #### Parameters:
| $obj |
[ Top ] ### method exists [line 396]
`true exists( )`
Tests whether the file denoted by this abstract pathname exists. #### Tags:
return: | if and only if the file denoted by this abstract pathname exists; false otherwise
[ Top ] ### method getAbsoluteFile [line 254]
`The getAbsoluteFile( )`
Returns the absolute form of this abstract pathname. Equivalent to getAbsolutePath. #### Tags:
return: | absolute abstract pathname denoting the same file or directory as this abstract pathname
[ Top ] ### method getAbsolutePath [line 242]
`The getAbsolutePath( )`
Returns the absolute pathname string of this abstract pathname. If this abstract pathname is already absolute, then the pathname string is simply returned as if by the getPath method. If this abstract pathname is the empty abstract pathname then the pathname string of the current user directory, which is named by the system property user.dir, is returned. Otherwise this pathname is resolved in a system-dependent way. On UNIX systems, a relative pathname is made absolute by resolving it against the current user directory. On Win32 systems, a relative pathname is made absolute by resolving it against the current directory of the drive named by the pathname, if any; if not, it is resolved against the current user directory. #### Tags:
return: | absolute pathname string denoting the same file or directory as this abstract pathname
see: | #isAbsolute()
[ Top ] ### method getCanonicalFile [line 296]
`PhingFile getCanonicalFile( )`
Returns the canonical form of this abstract pathname. Equivalent to getCanonicalPath(. #### Tags:
return: | The canonical pathname string denoting the same file or directory as this abstract pathname
[ Top ] ### method getCanonicalPath [line 283]
`The getCanonicalPath( )`
Returns the canonical pathname string of this abstract pathname. A canonical pathname is both absolute and unique. The precise definition of canonical form is system-dependent. This method first converts this pathname to absolute form if necessary, as if by invoking the getAbsolutePath() method, and then maps it to its unique form in a system-dependent way. This typically involves removing redundant names such as "." and .. from the pathname, resolving symbolic links (on UNIX platforms), and converting drive letters to a standard case (on Win32 platforms). Every pathname that denotes an existing file or directory has a unique canonical form. Every pathname that denotes a nonexistent file or directory also has a unique canonical form. The canonical form of the pathname of a nonexistent file or directory may be different from the canonical form of the same pathname after the file or directory is created. Similarly, the canonical form of the pathname of an existing file or directory may be different from the canonical form of the same pathname after the file or directory is deleted. #### Tags:
return: | canonical pathname string denoting the same file or directory as this abstract pathname
[ Top ] ### method getLinkTarget [line 484]
`the getLinkTarget( )`
Returns the target of the symbolic link denoted by this abstract pathname #### Tags:
return: | target of the symbolic link denoted by this abstract pathname
access: | public
[ Top ] ### method getMode [line 772]
`int getMode( )`
Retrieve the mode of this file. [ Top ] ### method getName [line 144]
`The getName( )`
Returns the name of the file or directory denoted by this abstract pathname. This is just the last name in the pathname's name sequence. If the pathname's name sequence is empty, then the empty string is returned. #### Tags:
return: | name of the file or directory denoted by this abstract pathname, or the empty string if this pathname's name sequence is empty
[ Top ] ### method getParent [line 165]
`The getParent( )`
Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory. The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory. #### Tags:
return: | pathname string of the parent directory named by this abstract pathname, or null if this pathname does not name a parent
[ Top ] ### method getParentFile [line 190]
`The getParentFile( )`
Returns the abstract pathname of this abstract pathname's parent, or null if this pathname does not name a parent directory. The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory. #### Tags:
return: | abstract pathname of the parent directory named by this abstract pathname, or null if this pathname does not name a parent
[ Top ] ### method getPath [line 205]
`The getPath( )`
Converts this abstract pathname into a pathname string. The resulting string uses the default name-separator character to separate the names in the name sequence. #### Tags:
return: | string form of this abstract pathname
[ Top ] ### method getPrefixLength [line 75]
`void getPrefixLength( )`
Returns the length of this abstract pathname's prefix. [ Top ] ### method getTempDir [line 821]
`void getTempDir( )`
Returns the path to the temp directory. [ Top ] ### method getUser [line 755]
`int getUser( )`
Retrieve the owner of this file. #### Tags:
return: | User ID of the owner of this file.
[ Top ] ### method isAbsolute [line 218]
`true isAbsolute( )`
Tests whether this abstract pathname is absolute. The definition of absolute pathname is system dependent. On UNIX systems, a pathname is absolute if its prefix is "/". On Win32 systems, a pathname is absolute if its prefix is a drive specifier followed by "\\", or if its prefix is "\\". #### Tags:
return: | if this abstract pathname is absolute, false otherwise
[ Top ] ### method isDirectory [line 417]
`true isDirectory( )`
Tests whether the file denoted by this abstract pathname is a directory. #### Tags:
return: | if and only if the file denoted by this abstract pathname exists and is a directory; false otherwise
[ Top ] ### method isFile [line 436]
`true isFile( )`
Tests whether the file denoted by this abstract pathname is a normal file. A file is normal if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file. #### Tags:
return: | if and only if the file denoted by this abstract pathname exists and is a normal file; false otherwise
[ Top ] ### method isHidden [line 454]
`true isHidden( )`
Tests whether the file named by this abstract pathname is a hidden file. The exact definition of hidden is system-dependent. On UNIX systems, a file is considered to be hidden if its name begins with a period character ('.'). On Win32 systems, a file is considered to be hidden if it has been marked as such in the filesystem. Currently there seems to be no way to dermine isHidden on Win file systems via PHP #### Tags:
return: | if and only if the file denoted by this abstract pathname is hidden according to the conventions of the underlying platform
[ Top ] ### method isLink [line 469]
`true isLink( )`
Tests whether the file denoted by this abstract pathname is a symbolic link. #### Tags:
return: | if and only if the file denoted by this abstract pathname exists and is a symbolic link; false otherwise
access: | public
[ Top ] ### method lastModified [line 498]
`A lastModified( )`
Returns the time that the file denoted by this abstract pathname was last modified. #### Tags:
return: | integer value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0 if the file does not exist or if an I/O error occurs
[ Top ] ### method length [line 513]
`The length( )`
Returns the length of the file denoted by this abstract pathname. The return value is unspecified if this pathname denotes a directory. #### Tags:
return: | length, in bytes, of the file denoted by this abstract pathname, or 0 if the file does not exist
[ Top ] ### method listDir [line 606]
`An listDir( [ $filter = null])`
Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname. If this abstract pathname does not denote a directory, then this method returns null Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path. There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order. #### Tags:
return: | array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory, or if an I/O error occurs.
#### Parameters:
| $filter |
[ Top ] ### method listFiles [line 611]
`void listFiles( [ $filter = null])`
#### Parameters:
| $filter |
[ Top ] ### method listRoots [line 811]
`An listRoots( )`
List the available filesystem roots. A particular platform may support zero or more hierarchically-organized file systems. Each file system has a root directory from which all other files in that file system can be reached. Windows platforms, for example, have a root directory for each active drive; UNIX platforms have a single root directory, namely "/". The set of available filesystem roots is affected by various system-level operations such the insertion or ejection of removable media and the disconnecting or unmounting of physical or virtual disk drives. This method returns an array of PhingFile objects that denote the root directories of the available filesystem roots. It is guaranteed that the canonical pathname of any file physically present on the local machine will begin with one of the roots returned by this method. The canonical pathname of a file that resides on some other machine and is accessed via a remote-filesystem protocol such as SMB or NFS may or may not begin with one of the roots returned by this method. If the pathname of a remote file is syntactically indistinguishable from the pathname of a local file then it will begin with one of the roots returned by this method. Thus, for example, PhingFile objects denoting the root directories of the mapped network drives of a Windows platform will be returned by this method, while PhingFile objects containing UNC pathnames will not be returned by this method. #### Tags:
return: | array of PhingFile objects denoting the available filesystem roots, or null if the set of roots could not be determined. The array will be empty if there are no filesystem roots.
[ Top ] ### method mkdir [line 656]
`true mkdir( [ $mode = 0755])`
Creates the directory named by this abstract pathname. #### Tags:
return: | if and only if the directory was created; false otherwise
throws: | IOException
#### Parameters:
| $mode |
[ Top ] ### method mkdirs [line 635]
`true mkdirs( [ $mode = 0755])`
Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories. #### Tags:
return: | if and only if the directory was created, along with all necessary parent directories; false otherwise
throws: | IOException
#### Parameters:
| $mode |
[ Top ] ### method removeTempFile [line 856]
`void removeTempFile( )`
If necessary, $File the lock on $File is removed and then the file is deleted #### Tags:
access: | public
[ Top ] ### method renameTo [line 671]
`true renameTo( PhingFile $destFile)`
Renames the file denoted by this abstract pathname. #### Tags:
return: | if and only if the renaming succeeded; false otherwise
#### Parameters:
destFile | $destFile | The new abstract pathname for the named file
[ Top ] ### method setLastModified [line 714]
`true setLastModified( time $time)`
Sets the last-modified time of the file or directory named by this abstract pathname. All platforms support file-modification times to the nearest second, but some provide more precision. The argument will be truncated to fit the supported precision. If the operation succeeds and no intervening operations on the file take place, then the next invocation of the lastModified method will return the (possibly truncated) time argument that was passed to this method. #### Tags:
return: | if and only if the operation succeeded; false otherwise
#### Parameters:
time | $time | The new last-modified time, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
[ Top ] ### method setMode [line 763]
`void setMode( int $mode)`
Sets the mode of the file #### Parameters:
int | $mode | Ocatal mode.
[ Top ] ### method setReadOnly [line 733]
`true setReadOnly( )`
Marks the file or directory named by this abstract pathname so that only read operations are allowed. After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access. Whether or not a read-only file or directory may be deleted depends upon the underlying system. #### Tags:
return: | if and only if the operation succeeded; false otherwise
[ Top ] ### method setUser [line 746]
`void setUser( mixed $user)`
Sets the owner of the file. #### Tags:
access: | public
#### Parameters:
mixed | $user | User name or number.
[ Top ] ### method toString [line 903]
`void toString( )`
Backwards compatibility -- use PHP5's native __tostring method. [ Top ] ### method toURI [line 327]
`void toURI( )`
Constructs a file: URI that represents this abstract pathname. Not implemented yet [ Top ] ### method toURL [line 316]
`A toURL( )`
Converts this abstract pathname into a file: URL. The exact form of the URL is system-dependent. If it can be determined that the file denoted by this abstract pathname is a directory, then the resulting URL will end with a slash. Usage note: This method does not automatically escape characters that are illegal in URLs. It is recommended that new code convert an abstract pathname into a URL by first converting it into a URI, via the toURI() method, and then converting the URI into a URL via the URI::toURL() #### Tags:
return: | URL object representing the equivalent file URL
[ Top ] ### method _constructFileParentStringChild [line 112]
`void _constructFileParentStringChild( $parent, [ $child = null])`
#### Parameters:
| $parent |
| $child |
[ Top ] ### method _constructPathname [line 81]
`void _constructPathname( $pathname)`
#### Parameters:
| $pathname |
[ Top ] ### method _constructStringParentStringChild [line 93]
`void _constructStringParentStringChild( $parent, [ $child = null])`
#### Parameters:
| $parent |
| $child |
[ Top ] ### method _slashify [line 337]
`void _slashify( $path, $isDirectory)`
#### Parameters:
| $path |
| $isDirectory |
[ Top ] ### method __toString [line 908]
`void __toString( )`
PHP5's native method. [ Top ] Documentation generated on Mon, 19 Oct 2009 10:51:34 +0200 by phpDocumentor 1.4.3