fFileclass implements Iteratorv1.0.0b30

Class Resources

Uses

Used By

Represents a file on the filesystem, also provides static file-related methods

Changes:

1.0.0b30	Changed the way files deleted in a filesystem transaction are handled, including improvements to the exception that is thrown 3/5/10
1.0.0b29	Fixed a couple of undefined variable errors in determineMimeTypeByContents() 3/3/10
1.0.0b28	Added support for some JPEG files created by Photoshop 12/16/09
1.0.0b27	Backwards Compatibility Break - renamed getFilename() to `getName()`, getFilesize() to `getSize()`, getDirectory() to `getParent()`, added `move()` 12/16/09
1.0.0b26	getDirectory(), getFilename() and `getPath()` now all work even if the file has been deleted 10/22/09
1.0.0b25	Fixed `__construct()` to throw an fValidationException when the file does not exist 8/21/09
1.0.0b24	Fixed a bug where deleting a file would prevent any future operations in the same script execution on a file or directory with the same path 8/20/09
1.0.0b23	Added the ability to skip checks in `__construct()` for better performance in conjunction with `fFilesystem::createObject()` 8/6/09
1.0.0b22	Fixed `__toString()` to never throw an exception 8/6/09
1.0.0b21	Fixed a bug in `determineMimeType()` 7/21/09
1.0.0b20	Fixed the exception message thrown by `output()` when output buffering is turned on 6/26/09
1.0.0b19	`rename()` will now rename the file in its current directory if the new filename has no directory separator 5/4/09
1.0.0b18	Changed `__sleep()` to not reset the iterator since it can cause side-effects 5/4/09
1.0.0b17	Added `__sleep()` and `__wakeup()` for proper serialization with the filesystem map 5/3/09
1.0.0b16	`output()` now accepts `TRUE` in the second parameter to use the current filename as the attachment filename 3/23/09
1.0.0b15	Added support for mime type detection of MP3s based on the MPEG-2 (as opposed to MPEG-1) standard 3/23/09
1.0.0b14	Fixed a bug with detecting the mime type of some MP3s 3/22/09
1.0.0b13	Fixed a bug with overwriting files via `rename()` on Windows 3/11/09
1.0.0b12	Backwards compatibility break - Changed the second parameter of `output()` from `$ignore_output_buffer` to `$filename` 3/5/09
1.0.0b11	Changed `__clone()` and `duplicate()` to copy file permissions to the new file 1/5/09
1.0.0b10	Fixed `duplicate()` so an exception is not thrown when no parameters are passed 1/5/09
1.0.0b9	Removed the dependency on fBuffer 1/5/09
1.0.0b8	Added the Iterator interface, `output()` and `getMTime()` 12/17/08
1.0.0b7	Removed some unnecessary error suppresion operators 12/11/08
1.0.0b6	Added the `__clone()` method that duplicates the file on the filesystem when cloned 12/11/08
1.0.0b5	Fixed detection of mime type for JPEG files with Exif information 12/4/08
1.0.0b4	Changed the constructor to ensure the path is to a file and not directory 11/24/08
1.0.0b3	Fixed mime type detection of Microsoft Office files 11/23/08
1.0.0b2	Made `rename()` and `write()` return the object for method chaining 11/22/08
1.0.0b	The initial implementation 6/14/07

Genealogy

Child Classes

fImage: Represents an image on the filesystem, also provides image manipulation functionality

Variables

->deletedprotected

A backtrace from when the file was deleted

Type

array

->fileprotected

The full path to the file

Type

string

Static Methods

::create() public

Creates a file on the filesystem and returns an object representing it.

This operation will be reverted by a filesystem transaction being rolled back.

Signature

fFile create( string $file_path, string $contents )

Parameters

string	$file_path	The path to the new file
string	$contents	The contents to write to the file, must be a non-NULL value to be written

Throws

fValidationException: When no file was specified or the file already exists

Overridden By

fImage::create(): Creates an image on the filesystem and returns an object representing it

::determineMimeType() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Determines the file's mime type by either looking at the file contents or matching the extension

Please see the getMimeType() description for details about how the mime type is determined and what mime types are detected.

Signature

string determineMimeType( string $file, string $contents=NULL )

Parameters

string	$file	The file to check the mime type for - must be a valid filesystem path if no `$contents` are provided, otherwise just a filename
string	$contents	The first 4096 bytes of the file content - the `$file` parameter only need be a filename if this is provided

Returns

The mime type of the file

Methods

->__construct() public

Creates an object to represent a file on the filesystem

If multiple fFile objects are created for a single file, they will reflect changes in each other including rename and delete actions.

Signature

fFile __construct( string $file, boolean $skip_checks=FALSE )

Parameters

string	$file	The path to the file
boolean	$skip_checks	If file checks should be skipped, which improves performance, but may cause undefined behavior - only skip these if they are duplicated elsewhere

Throws

fValidationException: When no file was specified, the file does not exist or the path specified is not a file

Overridden By

fImage::__construct(): Creates an object to represent an image on the filesystem

->__clone() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Duplicates a file in the current directory when the object is cloned

Signature

fFile __clone( )

Returns

The new fFile object

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string

$method

The method to create a callback for

Returns

The callback for the method requested

->__sleep() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

The iterator information doesn't need to be serialized since a resource can't be

Signature

array __sleep( )

Returns

The instance variables to serialize

->__toString() public

Returns the filename of the file

Signature

string __toString( )

Returns

The filename

->__wakeup() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Re-inserts the file back into the filesystem map when unserialized

Signature

void __wakeup( )

->current() internal public implements Iterator

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Returns the current line of the file (required by iterator interface)

Signature

array current( )

Returns

The current row

Throws

fNoRemainingException: When there are no remaining lines in the file

->delete() public

Deletes the current file

This operation will NOT be performed until the filesystem transaction has been committed, if a transaction is in progress. Any non-Flourish code (PHP or system) will still see this file as existing until that point.

Signature

void delete( )

->duplicate() public

Creates a new file object with a copy of this file

If no directory is specified, the file is created with a new name in the current directory. If a new directory is specified, you must also indicate if you wish to overwrite an existing file with the same name in the new directory or create a unique name.

This operation will be reverted by a filesystem transaction being rolled back.

Signature

fFile duplicate( string|fDirectory $new_directory=NULL, boolean $overwrite=NULL )

Parameters

string\|fDirectory	$new_directory	The directory to duplicate the file into if different than the current directory
boolean	$overwrite	If a new directory is specified, this indicates if a file with the same name should be overwritten.

Returns

The new fFile object

->getMimeType() public

Gets the file's mime type

This method will attempt to look at the file contents and the file extension to determine the mime type. If the file contains binary information, the contents will be used for mime type verification, however if the contents appear to be plain text, the file extension will be used.

The following mime types are supported. All other binary file types will be returned as application/octet-stream and all other text files will be returned as text/plain.

Archive:

application/x-bzip2 BZip2 file
application/x-compress Compress (*nix) file
application/x-gzip GZip file
application/x-rar-compressed Rar file
application/x-stuffit StuffIt file
application/x-tar Tar file
application/zip Zip file

Audio:

audio/x-flac FLAC audio
audio/mpeg MP3 audio
audio/mp4 MP4 (AAC) audio
audio/vorbis Ogg Vorbis audio
audio/x-wav WAV audio
audio/x-ms-wma Windows media audio

Document:

application/vnd.ms-excel Excel (2000, 2003 and 2007) file
application/pdf PDF file
application/vnd.ms-powerpoint Powerpoint (2000, 2003, 2007) file
text/rtf RTF file
application/msword Word (2000, 2003 and 2007) file

Image:

image/x-ms-bmp BMP file
application/postscript EPS file
image/gif GIF file
application/vnd.microsoft.icon ICO file
image/jpeg JPEG file
image/png PNG file
image/tiff TIFF file
image/svg+xml SVG file

Text:

text/css CSS file
text/csv CSV file
text/html (X)HTML file
text/calendar iCalendar file
application/javascript Javascript file
application/x-perl Perl file
application/x-httpd-php PHP file
application/x-python Python file
application/rss+xml RSS feed
application/x-ruby Ruby file
text/tab-separated-values TAB file
text/x-vcard VCard file
application/xhtml+xml XHTML (Real) file
application/xml XML file

Video/Animation:

video/x-msvideo AVI video
application/x-shockwave-flash Flash movie
video/x-flv Flash video
video/x-ms-asf Microsoft ASF video
video/mp4 MP4 video
video/ogg OGM and Ogg Theora video
video/quicktime Quicktime video
video/x-ms-wmv Windows media video

Signature

string getMimeType( )

Returns

The mime type of the file

->getMTime() public

Returns the last modification time of the file

Signature

fTimestamp getMTime( )

Returns

The timestamp of when the file was last modified

->getName() public

Gets the filename (i.e. does not include the directory)

Signature

string getName( )

Returns

The filename of the file

->getParent() public

Gets the directory the file is located in

Signature

fDirectory getParent( )

Returns

The directory containing the file

->getPath() public

Gets the file's current path (directory and filename)

If the web path is requested, uses translations set with fFilesystem::addWebPathTranslation()

Signature

string getPath( boolean $translate_to_web_path=FALSE )

Parameters

boolean

$translate_to_web_path

If the path should be the web path

Returns

The path (directory and filename) for the file

->getSize() public

Gets the size of the file

The return value may be incorrect for files over 2GB on 32-bit OSes.

Signature

integer|string getSize( boolean $format=FALSE, integer $decimal_places=1 )

Parameters

boolean	$format	If the filesize should be formatted for human readability
integer	$decimal_places	The number of decimal places to format to (if enabled)

Returns

If formatted a string with filesize in b/kb/mb/gb/tb, otherwise an integer

->isWritable() public

Check to see if the current file is writable

Signature

boolean isWritable( )

Returns

If the file is writable

->key() internal public implements Iterator

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Returns the current one-based line number (required by iterator interface)

Signature

integer key( )

Returns

The current line number

Throws

fNoRemainingException: When there are no remaining lines in the file

->move() public

Moves the current file to a different directory

Please note that rename() will rename a file in its directory or rename it into a different directory.

If the current file's filename already exists in the new directory and the overwrite flag is set to false, the filename will be changed to a unique name.

This operation will be reverted if a filesystem transaction is in progress and is later rolled back.

Signature

fFile move( fDirectory|string $new_directory, boolean $overwrite )

Parameters

fDirectory\|string	$new_directory	The directory to move this file into
boolean	$overwrite	If the current filename already exists in the new directory, `TRUE` will cause the file to be overwritten, `FALSE` will cause the new filename to change

Returns

The file object, to allow for method chaining

Throws

fValidationException: When the directory passed is not a directory or is not readable

->next() internal public implements Iterator

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Advances to the next line in the file (required by iterator interface)

Signature

void next( )

Throws

fNoRemainingException: When there are no remaining lines in the file

->output() public

Prints the contents of the file

This method is primarily intended for when PHP is used to control access to files.

Be sure to turn off output buffering and close the session, if open, to prevent performance issues.

Signature

fFile output( boolean $headers, mixed $filename=NULL )

Parameters

boolean	$headers	If HTTP headers for the file should be included
mixed	$filename	Present the file as an attachment instead of just outputting type headers - if a string is passed, that will be used for the filename, if `TRUE` is passed, the current filename will be used

Returns

The file object, to allow for method chaining

->read() public

Reads the data from the file

Reads all file data into memory, use with caution on large files!

This operation will read the data that has been written during the current transaction if one is in progress.

Signature

string read( mixed $data )

Parameters

mixed

$data

The data to write to the file

Returns

The contents of the file

->rename() public

Renames the current file

If the filename already exists and the overwrite flag is set to false, a new filename will be created.

This operation will be reverted if a filesystem transaction is in progress and is later rolled back.

Signature

fFile rename( string $new_filename, boolean $overwrite )

Parameters

string	$new_filename	The new full path to the file or a new filename in the current directory
boolean	$overwrite	If the new filename already exists, `TRUE` will cause the file to be overwritten, `FALSE` will cause the new filename to change

Returns

The file object, to allow for method chaining

->rewind() internal public implements Iterator

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Rewinds the file handle (required by iterator interface)

Signature

void rewind( )

->tossIfDeleted() protected

Throws an fProgrammerException if the file has been deleted

Signature

void tossIfDeleted( )

->valid() internal public implements Iterator

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Returns if the file has any lines left (required by iterator interface)

Signature

boolean valid( )

Returns

If the iterator is still valid

->write() public

Writes the provided data to the file

Requires all previous data to be stored in memory if inside a transaction, use with caution on large files!

If a filesystem transaction is in progress and is rolled back, the previous data will be restored.

Signature

fFile write( mixed $data )

Parameters

mixed

$data

The data to write to the file

Returns

The file object, to allow for method chaining