PHP Class CFile

Show file Open project: idlesign/ist-yii-cfile Class Usage Examples

Public Methods

Method Description
__toString ( ) : string Returns filesystem object filepath.
copy ( string $dest ) : CFile | boolean Copies the current filesystem object to specified destination.
create ( ) : CFile | boolean Creates empty file if the current file doesn't exist.
createDir ( integer | string $permissions = 492, null | string $directory = null ) : boolean | CFile Creates empty directory defined either through {@link set} or through the $directory parameter.
delete ( boolean $purge = True ) : boolean Deletes the current filesystem object.
download ( null | string $fake_name = null, boolean $server_handled = False, null | string $content_type = null ) : boolean | null Alias for {@link send}.
getBasename ( ) : string Returns the current file basename (file name plus extension) from $_basename property set by {@link pathInfo} (e.g.: 'myfile.htm' for '/var/www/htdocs/files/myfile.htm').
getContents ( boolean $recursive = False, string $filter = null ) : string | array | boolean Returns the current filesystem object contents.
getDirname ( ) : string Returns the current file directory name (without final slash) from $_dirname property set by {@link pathInfo} (e.g.: '/var/www/htdocs/files' for '/var/www/htdocs/files/myfile.htm')
getExists ( ) : boolean Tests current filesystem object existence and returns boolean (see {@link exists}).
getExtension ( ) : string Returns the current file extension from $_extension property set by {@link pathInfo} (e.g.: 'htm' for '/var/www/htdocs/files/myfile.htm').
getFilename ( ) : string Returns the current file name (without extension) from $_filename property set by {@link pathInfo} (e.g.: 'myfile' for '/var/www/htdocs/files/myfile.htm')
getGroup ( boolean $get_name = True ) : integer | string | boolean Returns group of current filesystem object (UNIX systems).
getInstance ( string $filepath, string $class_name = __CLASS__ ) : object Returns the instance of CFile for the specified file.
getIsDir ( ) : boolean Returns filesystem object type for the current file (see {@link pathInfo}).
getIsEmpty ( ) : boolean Returns filesystem object has-contents flag.
getIsFile ( ) : boolean Returns filesystem object type for the current file (see {@link pathInfo}).
getIsUploaded ( ) : boolean Tells whether file is uploaded through a web form.
getMimeType ( ) : string | boolean Returns the MIME type of the current file.
getMimeTypeByExtension ( ) : string Determines the MIME type based on the extension of the current file.
getOwner ( boolean $get_name = True ) : integer | string | boolean Returns owner of current filesystem object (UNIX systems).
getPermissions ( ) : string Returns permissions of current filesystem object (UNIX systems).
getReadable ( ) : boolean Tests whether the current filesystem object is readable and returns boolean.
getRealPath ( string $dir_separator = DIRECTORY_SEPARATOR ) : string Returns real filesystem object path figured by script (see {@link realPath}) on the basis of user supplied $_filepath.
getRelativePath ( ) : string Returns relative filesystem object path figured by script on the basis of $_realpath
getSize ( string | boolean $format = '0.00' ) : string | integer Returns size of current filesystem object.
getTimeCreated ( ) : integer Returns the current file created time. Works on Windows System only! Returned Unix timestamp could be passed to php date() function.
getTimeModified ( ) : integer Returns the current file last modified time.
getWriteable ( ) : boolean Tests whether the current filesystem object is readable and returns boolean.
move ( string $dest ) : CFile | boolean Alias for {@link rename}.
purge ( null | string $path = null ) : boolean | CFile Purges (makes empty) the current filesystem object.
rename ( string $dest ) : CFile | boolean Renames/moves the current filesystem object to specified destination.
send ( null | string $fake_name = null, boolean $server_handled = False, null | string $content_type = null ) : boolean | null Sends the current file to browser as a download with real or faked file name.
set ( string $filepath, boolean $greedy = False ) : object Basic CFile method. Sets CFile object to work with specified filesystem object.
setBasename ( null | string $basename = null ) : boolean | CFile Sets basename for the current file.
setContents ( string $contents = null, boolean $autocreate = True, integer $flags ) : CFile | boolean Writes contents (data) into the current file.
setExtension ( null | boolean | string $extension = False ) : boolean | CFile Sets the current file extension.
setFilename ( null | string $filename = null ) : boolean | CFile Sets the current file name.
setGroup ( string | integer $group, boolean $recursive = False ) : CFile | boolean Sets the current filesystem object group, updates $_group property on success.
setOwner ( string | integer $owner, boolean $recursive = False ) : CFile | boolean Sets the current filesystem object owner, updates $_owner property on success.
setPermissions ( string $permissions, boolean $recursive = False ) : CFile | boolean Sets the current filesystem object permissions, updates $_permissions property on success.

Protected Methods

Method Description
addLog ( string $message, string $level = 'info' ) Logs a message.
formatNumber ( number $number, string $format ) : string Formats a given number into a given format and returns it.
getPathOfAlias ( string $alias ) : boolean | string Returns filepath for a given alias.

Private Methods

Method Description
close ( ) Closes (if opened) the current file pointer.
dirContents ( null | string $directory = null, boolean $recursive = False, null | string $filter = null ) : array Gets directory contents (descendant files and folders).
dirSize ( ) : integer Calculates the current directory size recursively fetching sizes of all descendant files.
exists ( ) : boolean Base filesystem object existence resolving method.
filterPassed ( string $str, array $filter ) : boolean Applies an array of filter rules to the string representing filepath.
formatFileSize ( integer $bytes, string $format = '0.00' ) : string Base filesystem object size format method.
open ( string $mode ) : boolean | CFile Opens (if not already opened) the current file using certain mode.
pathInfo ( ) Populates basic CFile properties (i.e. 'Dirname', 'Basename', etc.) using values resolved by pathinfo() php function.
realPath ( string $supplied_path, string $dir_separator = DIRECTORY_SEPARATOR ) : string Base real filesystem object path resolving method.
resolveDestPath ( string $dest ) : string Resolves destination path for the current filesystem object.

Method Details

__toString() public method

Returns filesystem object filepath.
public __toString ( ) : string
return string

addLog() protected method

Logs a message.
protected addLog ( string $message, string $level = 'info' )
$message string Message to be logged
$level string Level of the message (e.g. 'trace', 'warning', 'error', 'info', see CLogger constants definitions)

copy() public method

Destination path supplied by user resolved to real destination path with {@link resolveDestPath}
public copy ( string $dest ) : CFile | boolean
$dest string Destination path for the current filesystem object to be copied to
return CFile | boolean New CFile object for newly created filesystem object on success, 'False' on fail.

create() public method

Creates empty file if the current file doesn't exist.
public create ( ) : CFile | boolean
return CFile | boolean Updated the current CFile object on success, 'False' on fail.

createDir() public method

Creates empty directory defined either through {@link set} or through the $directory parameter.
public createDir ( integer | string $permissions = 492, null | string $directory = null ) : boolean | CFile
$permissions integer | string Access permissions for the directory
$directory null | string Parameter used to create directory other than supplied by {@link set} method of the CFile
return boolean | CFile Updated the current CFile object on success, 'False' on fail.

delete() public method

For folders purge parameter can be supplied.
public delete ( boolean $purge = True ) : boolean
$purge boolean If 'True' folder would be deleted with all the descendants
return boolean 'True' if successfully deleted, 'False' on fail

download() public method

Alias for {@link send}.
public download ( null | string $fake_name = null, boolean $server_handled = False, null | string $content_type = null ) : boolean | null
$fake_name null | string
$server_handled boolean
$content_type null | string
return boolean | null

formatNumber() protected method

See {@link CNumberFormatter}.
protected formatNumber ( number $number, string $format ) : string
$number number
$format string
return string

getBasename() public method

Returns the current file basename (file name plus extension) from $_basename property set by {@link pathInfo} (e.g.: 'myfile.htm' for '/var/www/htdocs/files/myfile.htm').
public getBasename ( ) : string
return string Current file basename

getContents() public method

Reads data from filesystem object if it is a regular file. List files and directories inside the specified path if filesystem object is a directory.
public getContents ( boolean $recursive = False, string $filter = null ) : string | array | boolean
$recursive boolean If True method would return all directory descendants.
$filter string Filter to be applied to all directory descendants. Could be a string, or an array of strings (perl regexp are supported, if started with '~').
return string | array | boolean Data read for files, or directory contents names array. False on fail.

getDirname() public method

Returns the current file directory name (without final slash) from $_dirname property set by {@link pathInfo} (e.g.: '/var/www/htdocs/files' for '/var/www/htdocs/files/myfile.htm')
public getDirname ( ) : string
return string Current file directory name

getExists() public method

If $_exists property is set, returned value is read from that property.
public getExists ( ) : boolean
return boolean 'True' if file exists, otherwise 'False'

getExtension() public method

Returns the current file extension from $_extension property set by {@link pathInfo} (e.g.: 'htm' for '/var/www/htdocs/files/myfile.htm').
public getExtension ( ) : string
return string Current file extension without the leading dot

getFilename() public method

Returns the current file name (without extension) from $_filename property set by {@link pathInfo} (e.g.: 'myfile' for '/var/www/htdocs/files/myfile.htm')
public getFilename ( ) : string
return string Current file name

getGroup() public method

Returned value depends upon $getName parameter value. If $_group property is set, returned value is read from that property.
public getGroup ( boolean $get_name = True ) : integer | string | boolean
$get_name boolean Defaults to 'True', meaning that group name instead of ID should be returned.
return integer | string | boolean Group name, or ID if $getName set to 'False'

getInstance() public static method

Returns the instance of CFile for the specified file.
public static getInstance ( string $filepath, string $class_name = __CLASS__ ) : object
$filepath string Path to file specified by user.
$class_name string Class name to spawn object for.
return object CFile instance

getIsDir() public method

Tells whether filesystem object is a directory.
public getIsDir ( ) : boolean
return boolean 'True' if filesystem object is a directory, otherwise 'False'

getIsEmpty() public method

Directory considered empty if it doesn't contain descendants. File considered empty if its size is 0 bytes.
public getIsEmpty ( ) : boolean
return boolean 'True' if file is a directory, otherwise 'False'

getIsFile() public method

Tells whether filesystem object is a regular file.
public getIsFile ( ) : boolean
return boolean 'True' if filesystem object is a regular file, otherwise 'False'

getIsUploaded() public method

Tells whether file is uploaded through a web form.
public getIsUploaded ( ) : boolean
return boolean 'True' if file is uploaded, otherwise 'False'

getMimeType() public method

If $_mime_type property is set, returned value is read from that property. This method will attempt the following approaches in order: 1. finfo 2. mime_content_type 3. {@link getMimeTypeByExtension} This method works only for files.
public getMimeType ( ) : string | boolean
return string | boolean the MIME type on success, 'False' on fail.

getMimeTypeByExtension() public method

This method will use a local map between extension name and MIME type. This method works only for files.
public getMimeTypeByExtension ( ) : string
return string the MIME type. False is returned if the MIME type cannot be determined.

getOwner() public method

Returned value depends upon $getName parameter value. If $_owner property is set, returned value is read from that property.
public getOwner ( boolean $get_name = True ) : integer | string | boolean
$get_name boolean Defaults to 'True', meaning that owner name instead of ID should be returned.
return integer | string | boolean Owner name, or ID if $getName set to 'False'

getPathOfAlias() protected method

Returns filepath for a given alias.
protected getPathOfAlias ( string $alias ) : boolean | string
$alias string
return boolean | string

getPermissions() public method

If $_permissions property is set, returned value is read from that property.
public getPermissions ( ) : string
return string Filesystem object permissions in octal format (i.e. '0755')

getReadable() public method

If $_readable property is set, returned value is read from that property.
public getReadable ( ) : boolean
return boolean 'True' if filesystem object is readable, otherwise 'False'

getRealPath() public method

If $_realpath property is set, returned value is read from that property.
public getRealPath ( string $dir_separator = DIRECTORY_SEPARATOR ) : string
$dir_separator string Directory separator char (depends upon OS)
return string Real file path

getRelativePath() public method

Returns relative filesystem object path figured by script on the basis of $_realpath
public getRelativePath ( ) : string
return string Relative file path

getSize() public method

Returned value depends upon $format parameter value. If $_size property is set, returned value is read from that property. Uses {@link dirSize} method for directory size calculation.
public getSize ( string | boolean $format = '0.00' ) : string | integer
$format string | boolean Number format or 'False'
return string | integer Filesystem object size formatted (e.g.: '70.4 KB') or in bytes (e.g.: '72081') if $format set to 'False'

getTimeCreated() public method

Returns the current file created time. Works on Windows System only! Returned Unix timestamp could be passed to php date() function.
public getTimeCreated ( ) : integer
return integer created at time Unix timestamp (e.g.: '1213760802')

getTimeModified() public method

Returned Unix timestamp could be passed to php date() function.
public getTimeModified ( ) : integer
return integer Last modified time Unix timestamp (e.g.: '1213760802')

getWriteable() public method

If $_writeable property is set, returned value is read from that property.
public getWriteable ( ) : boolean
return boolean 'True' if filesystem object is writeable, otherwise 'False'

move() public method

Alias for {@link rename}.
public move ( string $dest ) : CFile | boolean
$dest string
return CFile | boolean

purge() public method

If the current filesystem object is a file its contents set to ''. If the current filesystem object is a directory all its descendants are deleted.
public purge ( null | string $path = null ) : boolean | CFile
$path null | string Filesystem path to object to purge.
return boolean | CFile Current CFile object on success, 'False' on fail.

rename() public method

Destination path supplied by user resolved to real destination path with {@link resolveDestPath}
public rename ( string $dest ) : CFile | boolean
$dest string Destination path for the current filesystem object to be renamed/moved to
return CFile | boolean Updated current CFile object on success, 'False' on fail.

send() public method

Browser caching is prevented. This method works only for files.
public send ( null | string $fake_name = null, boolean $server_handled = False, null | string $content_type = null ) : boolean | null
$fake_name null | string New filename (e.g.: 'myfileFakedName.htm')
$server_handled boolean Whether file contents delivery is handled by server internals (cf. when file contents is read and sent by php). E.g.: lighttpd and Apache with mod-sendfile can use X-Senfile header to speed up file delivery blazingly. Note: If you want to serve big or even huge files you are definetly advised to turn this option on and setup your server software appropriately, if not to say that it is your only alternative :).
$content_type null | string Should be used to override content type on demand.
return boolean | null Returns bool or outputs file contents with headers.

set() public method

Essentially path supplied by user is resolved into real path (see {@link getRealPath}), all the other property getting methods should use that real path. Uploaded files are supported through {@link CUploadedFile} Yii class. Path aliases are supported through {@link getPathOfAlias} Yii method.
public set ( string $filepath, boolean $greedy = False ) : object
$filepath string Path to the file specified by user, if not set exception is raised
$greedy boolean If True file properties (such as 'Size', 'Owner', 'Permission', etc.) would be autoloaded
return object CFile instance for the specified filesystem object

setBasename() public method

Lazy wrapper for {@link rename}. This method works only for files.
public setBasename ( null | string $basename = null ) : boolean | CFile
$basename null | string New file basename (e.g.: 'mynewfile.txt')
return boolean | CFile Current CFile object on success, 'False' on fail.

setContents() public method

This method works only for files.
public setContents ( string $contents = null, boolean $autocreate = True, integer $flags ) : CFile | boolean
$contents string Contents to be written
$autocreate boolean If 'True' file will be created automatically
$flags integer Flags for file_put_contents(). E.g.: FILE_APPEND to append data to file instead of overwriting.
return CFile | boolean Current CFile object on success, 'False' on fail.

setExtension() public method

If new extension is 'null' or 'False' current file extension is dropped. Lazy wrapper for {@link rename}. This method works only for files.
public setExtension ( null | boolean | string $extension = False ) : boolean | CFile
$extension null | boolean | string New file extension (e.g.: 'txt'). Pass null to drop current extension.
return boolean | CFile Current CFile object on success, 'False' on fail.

setFilename() public method

Lazy wrapper for {@link rename}. This method works only for files.
public setFilename ( null | string $filename = null ) : boolean | CFile
$filename null | string New file name (e.g.: 'mynewfile')
return boolean | CFile Current CFile object on success, 'False' on fail.

setGroup() public method

For POSIX systems. Asserts that group exists before process if posix_ functions are available.
public setGroup ( string | integer $group, boolean $recursive = False ) : CFile | boolean
$group string | integer New group name or ID
$recursive boolean Apply group to directory contents flag.
return CFile | boolean Current CFile object on success, 'False' on fail.

setOwner() public method

For POSIX systems. Asserts that user exists before process if posix_ functions are available.
public setOwner ( string | integer $owner, boolean $recursive = False ) : CFile | boolean
$owner string | integer New owner name or ID
$recursive boolean Apply owner to directory contents flag.
return CFile | boolean Current CFile object on success, 'False' on fail.

setPermissions() public method

For UNIX systems.
public setPermissions ( string $permissions, boolean $recursive = False ) : CFile | boolean
$permissions string New filesystem object permissions in numeric (octal, i.e. '0755') format
$recursive boolean Apply permissions to directory contents flag.
return CFile | boolean Current CFile object on success, 'False' on fail.