File Usage - Classes - FuelPHP Documentation

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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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).

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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, $area = null)

Rename directory or file.

Static Yes

パラメータ

パラメータ	規定値	説明
`$path`	必須	Location of the file or directory to rename
`$new_path`	必須	New name of the file or directory
`$area`	`null`	Area object to use, 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_dir($path, $new_path, $area = null)

Alias for File::rename

Static Yes

パラメータ

パラメータ	規定値	説明
`$path`	必須	Location of the file or directory to rename
`$new_path`	必須	New name of the file or directory
`$area`	`null`	Area object to use, 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)

Copies a file.

Static Yes

パラメータ

パラメータ	規定値	説明
`$path`	必須	Location of the file to copy
`$new_path`	必須	Full path, including filename, to copy to
`$area`	`null`	Area object to use, 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_dir($path, $new_path, $area = null)

Copies a directory.

Static Yes

パラメータ

パラメータ	規定値	説明
`$path`	必須	Location of the directory to copy
`$new_path`	必須	Path to copy to
`$area`	`null`	Area object to use, defaults to main config (see advanced usage for more information)

返り値 boolean result of copy()

例外 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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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.

Static Yes

パラメータ

パラメータ	規定値	説明
`$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');