File Class

The File class offers a set of methods to working with files & directories. This can be done through some helper methods or through a more advanced object oriented method where all files and directories are wrapped in objects.

Usage

The File class's basic usage is through its helper methods which are listed below.

exists($path, $area = null)

Checks if a file exists. If $path points to a symlink, the symlinks are resolved to make sure whatever it points to is a file.

Static Yes
Parameters
Param Default Description
$path required Location of the file to check
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns boolean true if the file in $path exists, false if not
Throws OutsideAreaException when a path not inside the file area. FileAccessException when an area is used and there is an extension violation.
Example 
$exists = File::exists(DOCROOT.'/test.txt');

create($basepath, $name, $contents = null, $area = null)

Create a file.

Static Yes
Parameters
Param Default Description
$basepath required Location to create the new file in
$name required Filename for the new file
$contents null What to put into the new file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns true
Throws FileAccessException when the file already exists. InvalidPathException when the basepath in not valid or not writable.
Example 
File::create(DOCROOT, 'test.txt', 'Contents for file.');

create_dir($basepath, $name, $chmod = 0777, $area = null)

Create a directory.

Static Yes
Parameters
Param Default Description
$basepath required Location to create the new directory in
$name required Name for the new directory
$chmod null Rights for the new directory
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns bool - the output of the mkdir() PHP function
Throws InvalidPathException when the basepath does not exist or is not writable. FileAccessException when the basepath is not writable.
Example 
File::create_dir(DOCROOT, 'test', 0755);

read($path, $as_string = false, $area = null)

Reads a file and returns it ($as_string == true) or adds it to the output ($as_string == false).

Static Yes
Parameters
Param Default Description
$path required Location of the file to read
$as_string false Makes it use readfile() on false or file_get_contents() on true
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns int|string - returns the number of bytes when $as_string was set to false or the file's contents as a string when it was set to true.
Throws InvalidPathException when the file does not exist.
Example 
// Returns 'Contents for file.' if you created the file in the example for File::create()
$file_content = File::read(DOCROOT.'test.txt', true);

read_dir($path, $depth = 0, $filter = null, $area = null)

Reads directory contents into an array.

Static Yes
Parameters
Param Default Description
$path required Location of the directory to read
$depth 0 How deep the subdirectories are recurred: 0 for unlimited, 1 for only the current directory or specific number.
$filter null A filter for which files to read: array() for all or null for all but hidden.
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns array - a natural-case sorted array with subdirectories on top. Directories have a string key with array value (or false when not read because of $depth limitation) and files are int indexed with filename as value. All directories are suffixed with a directory separator.
Throws InvalidPathException when the path not a directory. FileAccessException when the path is not readable.
Example 
// Read a directory
$contents = File::read_dir(DOCROOT);

// Read with a limited dept
$contents = File::read_dir(DOCROOT, 2);

// Read with custom rules
$contents = File::read_dir(DOCROOT, 0, array(
	'!^\.', // no hidden files/dirs
	'!^private' => 'dir', // no private dirs
	'\.png$' => 'file', // only get png's
	'\.css$' => 'file', // or css files
	'!^_', // exclude everything that starts with an underscore.
));

/**
 * As you can see above, you can make
 * rules directory or file specific by
 * adding "=> 'file'" or "=> 'dir'"
 * behind the rule.
 */

update($basepath, $name, $contents = null, $area = null)

Updates a file.

Static Yes
Parameters
Param Default Description
$basepath required Location of the file to update
$name required Filename for the file. If it does not exist, it will be created
$contents null What to put into the file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns true
Throws InvalidPathException when the basepath not a directory or is not writable. FileAccessException when there is no write access.
Example 
File::update(DOCROOT, 'test.txt', 'New contents for file.');

append($basepath, $name, $contents = null, $area = null)

Appends to an existing file.

Static Yes
Parameters
Param Default Description
$basepath required Location of the file to append to
$name required Filename for the file. This file has to exist
$contents null What to add to the file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns true
Throws InvalidPathException when the basepath not a directory or is not writable. FileAccessException when the file does not exist.
Example 
File::append(DOCROOT, 'test.txt', 'Additional contents for file.');

rename($path, $new_path, $source_area = null, $target_area = null)

Rename or move a directory or file.

Static Yes
Parameters
Param Default Description
$path required Location of the file or directory to rename
$new_path required New name of the file or directory
$source_area null Area object to use, null for base_config in config file (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, null for base_config in config file (see advanced usage for more information)
Returns boolean result of rename()
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the filetype is not allowed.
Example 
// rename 'test.txt' to 'newname.txt', and move it to a sub-directory
File::rename(DOCROOT.'test.txt', DOCROOT.'folder/newname.txt');

// rename using a single area
File::rename(DOCROOT.'one.jpg', DOCROOT.'final.jpg', 'docroot');

// move and rename between two restrictive areas
File::rename(APPPATH.'tmp/file.jpg', DOCROOT.'folder/image.jpg', 'tmp', 'public');

rename_dir($path, $new_path, $source_area = null, $target_area = null)

Alias for File::rename

Static Yes
Parameters
Param Default Description
$path required Location of the file or directory to rename
$new_path required New name of the file or directory
$source_area null Area object to use, null for base_config in config file (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, null for base_config in config file (see advanced usage for more information)
Returns boolean result of rename()
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the filetype is not allowed.
Example 
File::rename(DOCROOT.'/dirname', DOCROOT.'/newdirname');

copy($path, $new_path, $area = null, $source_area = null, $target_area = null)

Copies a file.

Static Yes
Parameters
Param Default Description
$path required Location of the file to copy
$new_path required Full path, including filename, to copy to
$source_area null Area object to use, null for base_config in config file (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, null for base_config in config file (see advanced usage for more information)
Returns boolean result of copy()
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the filetype is not allowed. InvalidPathException when the source path is not a file. FileAccessException when the destination file already exists.
Example 
// copy the file 'test.txt' from the docroot to a sub directory
File::copy(DOCROOT.'test.txt', DOCROOT.'folder/test.txt');

// copy using a single area
File::copy(DOCROOT.'one.jpg', DOCROOT.'img/one.jpg', 'public');

// copy between two restrictive areas
File::copy(APPPATH.'tmp/1.jpg', DOCROOT.'folder/1.jpg', 'tmp', 'public');

copy_dir($path, $new_path, $area = null, $source_area = null, $target_area = null)

Copies a directory.

Static Yes
Parameters
Param Default Description
$path required Location of the directory to copy
$new_path required Path to copy to
$source_area null Area object to use, null for base_config in config file (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, null for base_config in config file (see advanced usage for more information)
Returns null
Throws OutsideAreaException when a path not inside the file area. InvalidPathException when the source path is not a directory. FileAccessException when the destination directory already exists.
Example 
File::copy_dir(DOCROOT.'/test', DOCROOT.'/newname');

delete($path, $area = null)

Deletes a file.

Static Yes
Parameters
Param Default Description
$path required Location of the file to delete
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns boolean result of unlink()
Throws OutsideAreaException when a path not inside the file area. InvalidPathException when the source path is not a file.
Example 
File::delete(DOCROOT.'/test.txt');

delete_dir($path, $recursive = true, $delete_top = true, $area = null)

Deletes a file.

Static Yes
Parameters
Param Default Description
$path required Location of the directory to delete
$recursive true Whether to also delete contents of subdirectories
$delete_top true whether to delete the parent dir itself when empty
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns boolean result of unlink() or true when not deleting content of subdirectories
Throws OutsideAreaException when a path not inside the file area. InvalidPathException when the source path is not a directory. FileAccessException when something went wrong during the delete process.
Example 
File::delete_dir(DOCROOT.'/my_dir');

open_file($path, $lock = true, $area = null)

Opens a file and optionally locks it.

Static Yes
Parameters
Param Default Description
$path required Location of the file to open
$lock true If true, lock exclusively. If false, don't lock. You can also pass an flock() value explicitly.
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns resource, the file resource
Throws OutsideAreaException when a path not inside the file area.
FileAccessException when the file could not be locked.
FileAccessException when an invalid $lock value is passed.
Example 
$resource = File::open_file(DOCROOT.'/my_dir/text.txt');

Please note that the $lock value is ignored if file locking is disabled in the base config (which is the default!).

close_file($resource, $area = null)

Closes a file and unlocks it.

Static Yes
Parameters
Param Default Description
$resource required An open file resource
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns boolean if a lock is used.
Example 
$resource = File::open_file(DOCROOT.'/my_dir/text.txt');
// Do something with the resource
File::close_file($resource);

get($path, $config = array(), $area = null)

Fetches a file handler for the given file. Read more about handlers.

Static Yes
Parameters
Param Default Description
$path required Path to the file or directory to be wrapped in a handler
$config array() optional config array
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns Returns a new file handler object.
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
Example 
$handler = File::get(DOCROOT.'/my_dir/text.txt');

get_url($path, $config = array(), $area = null)

Retrieves the public url to a file. A url must be set in the base config or in the area config of the used area.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$config array() optional config array
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns The public url for the file.
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
Example 
$url = File::get_url(DOCROOT.'/my_dir/text.txt');
// Returns something like: http://mydomain.com/mydir/text.txt

get_permissions($path, $area = null)

Retrieves the octal permissions for a file or directory.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns The octal file permissions
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
Example 
$permissions = File::get_permissions(DOCROOT.'/my_dir/text.txt');
// Returns "0755"

get_time($path, $type = 'modified', $area = null)

Retrieves the created or modified time of a file or directory.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$type 'modified' Type of time to retrieve. Must be modified or created
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns The file created/modified unix timestamp
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
Example 
$permissions = File::get_time(DOCROOT.'/my_dir/text.txt', 'created');

get_size($path, $area = null)

Retrieves size in bytes for a file.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns The file size in bytes.
Throws OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed. InvalidPathException when the file is not found.
Example 
$filesize = File::get_size(DOCROOT.'/my_dir/text.txt');

file_info($path, $area = null)

Retrieves an array of information about the specified file.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
Returns An array with file information items. The array will contain path, filename and extension information, the file size and permissions, the creation and last modified timestamps, the detected mime-type and the file's character set.
Throws InvalidPathException when the file is not found. InvalidArgumentException when the file info could be determined.
Example 
$filesize = File::file_info(DOCROOT.'/my_dir/text.txt');

download($path, $name = null, $mime = null, $area = null, $delete = false, $disposition = 'attachment')

Outputs a file, inline or as a downloaded attachment.

Static Yes
Parameters
Param Default Description
$path required Path to the file
$name null Override the file's default filename
$mime null Override the file's default mimetype
$area null Area object to use, null for base_config in config file (see advanced usage for more information)
$delete false Whether or not to delete the file after download
$disposition 'attachment' whether to download or output inline. Accepts 'attachment' or 'inline', and defaults to 'attachment'.
Returns n/a - this method exits after initiating the download.
Throws InvalidPathException when the file does not exist. InvalidArgumentException if no file info could be retrieved for the file. FileAccessException when the file could not be opened for read.
Example 
// download file
File::download(DOCROOT.'/my_dir/text.txt', 'newfile.txt');

// output an inline image, for use as an <img> tag source
File::download(DOCROOT.'/img/image.jpg', null, 'image/jpeg', null, false, 'inline');

Note that when you call this method, it doesn't immediately download the file. It will schedule a shutdown event in which the file is downloaded, and then terminates the script. This ensures that all FuelPHP shutdown functions, like updating sessions, will execute as normal.