File クラス

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.

使用方法

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

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

Create a file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$basepath 必須 Location to create the new file in
$name 必須 Filename for the new file
$contents null What to put into the new file
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 true
例外 FileAccessException when the file already exists. InvalidPathException when the basepath in not valid or not writable.
例 
File::create(DOCROOT, 'test.txt', 'Contents for file.');

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

Create a directory.

静的 はい
パラメータ
パラメータ デフォルト 説明
$basepath 必須 Location to create the new directory in
$name 必須 Name for the new directory
$chmod null Rights for the new directory
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 bool - the output of the mkdir() PHP function
例外 InvalidPathException when the basepath does not exist or is not writable. FileAccessException when the basepath is not writable.
例 
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).

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 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, defaults to main config (see advanced usage for more information)
返り値 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.
例外 InvalidPathException when the file does not exist.
例 
// 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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 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, defaults to main config (see advanced usage for more information)
返り値 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.
例外 InvalidPathException when the path not a directory. FileAccessException when the path is not readable.
例 
// 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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$basepath 必須 Location of the file to update
$name 必須 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, defaults to main config (see advanced usage for more information)
返り値 true
例外 InvalidPathException when the basepath not a directory or is not writable. FileAccessException when there is no write access.
例 
File::update(DOCROOT, 'test.txt', 'New contents for file.');

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

Appends to an existing file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$basepath 必須 Location of the file to append to
$name 必須 Filename for the file. This file has to exist
$contents null What to add to the file
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 true
例外 InvalidPathException when the basepath not a directory or is not writable. FileAccessException when the file does not exist.
例 
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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the file or directory to rename
$new_path 必須 New name of the file or directory
$source_area null Area object to use, defaults to main config (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, defaults to main config (see advanced usage for more information)
返り値 boolean result of rename()
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the filetype is not allowed.
例 
// 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

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the file or directory to rename
$new_path 必須 New name of the file or directory
$source_area null Area object to use, defaults to main config (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, defaults to main config (see advanced usage for more information)
返り値 boolean result of rename()
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the filetype is not allowed.
例 
File::rename(DOCROOT.'/dirname', DOCROOT.'/newdirname');

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

Copies a file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the file to copy
$new_path 必須 Full path, including filename, to copy to
$source_area null Area object to use, defaults to main config (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, defaults to main config (see advanced usage for more information)
返り値 boolean result of copy()
例外 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.
例 
// 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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the directory to copy
$new_path 必須 Path to copy to
$source_area null Area object to use, defaults to main config (see advanced usage for more information)
$target_area null Optional Area object to use if $source_area does not contain $new_path, defaults to main config (see advanced usage for more information)
返り値 null
例外 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.
例 
File::copy_dir(DOCROOT.'/test', DOCROOT.'/newname');

delete($path, $area = null)

Deletes a file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the file to delete
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 boolean result of unlink()
例外 OutsideAreaException when a path not inside the file area. InvalidPathException when the source path is not a file.
例 
File::delete(DOCROOT.'/test.txt');

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

Deletes a file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 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, defaults to main config (see advanced usage for more information)
返り値 boolean result of unlink() or true when not deleting content of subdirectories
例外 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.
例 
File::delete_dir(DOCROOT.'/my_dir');

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

Opens a file and locks it.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Location of the file to open
$lock true Whether to lock the file when opening.
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 resource, the file resource
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file could not be locked.
例 
$resource = File::open_file(DOCROOT.'/my_dir/text.txt');

close_file($resource, $area = null)

Closes a file and unlocks it.

静的 はい
パラメータ
パラメータ デフォルト 説明
$resource 必須 An open file resource
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 boolean if a lock is used.
例 
$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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file or directory to be wrapped in a handler
$config array() optional config array
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 Returns a new file handler object.
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
例 
$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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file
$config array() optional config array
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 The public url for the file.
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
例 
$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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 The octal file permissions
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
例 
$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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file
$type 'modified' Type of time to retrieve. Must be modified or created
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 The file created/modified unix timestamp
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed.
例 
$permissions = File::get_time(DOCROOT.'/my_dir/text.txt', 'created');

get_size($path, $area = null)

Retrieves size in bytes for a file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 The file size in bytes.
例外 OutsideAreaException when a path not inside the file area. FileAccessException when the file extension is not allowed. InvalidPathException when the file is not found.
例 
$filesize = File::get_size(DOCROOT.'/my_dir/text.txt');

file_info($path, $area = null)

Retrieves an array of information about the specified file.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 Path to the file
$area null Area object to use, defaults to main config (see advanced usage for more information)
返り値 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.
例外 InvalidPathException when the file is not found. InvalidArgumentException when the file info could be determined.
例 
$filesize = File::file_info(DOCROOT.'/my_dir/text.txt');

download($path, $name = null, $mime = null, $area = null)

Outputs a file as download.

静的 はい
パラメータ
パラメータ デフォルト 説明
$path 必須 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, defaults to main config (see advanced usage for more information)
返り値 n/a - this method exits after initiating the download.
例外 FileAccessException when the file could not be opened for read.
例 
File::download(DOCROOT.'/my_dir/text.txt', 'newfile.txt');