File 用法 - 类別

优质

小牛编辑

121浏览

2023-12-01

File 类别提供一系列的方法与档案＆目录协作。可以透过一些辅助方法完成，或透过更进阶的物件导向方法，其中所有的档案和目录被包裹在物件。

用法

File 类别的基础用法是透过以下所列它自己的辅助方法。

exists($path, $area = null)

检查档案是否存在。如果 $path 指向一个符号连结，该符号连结会被解析来确保它所指向的是否为一个档案。

静态是

参数

参数	预设	描述
`$path`	必要	要检查档案的位置
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 布林 true 如果 $path 中的档案存在，如果不存在的话为 false

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当区域已被使用而且有一个扩充侵犯。

範例

$exists = File::exists(DOCROOT.'/test.txt');

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

建立一个档案。

静态是

参数

参数	预设	描述
`$basepath`	必要	要建立新档案的位置
`$name`	必要	给新档案的档案名称
`$contents`	`null`	想要放进新档案的内容
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 true

抛出 FileAccessException 当档案已经存在。 InvalidPathException 当基础路径无效或不可写入。

範例

File::create(DOCROOT, 'test.txt', 'Contents for file.');

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

建立一个目录。

静态是

参数

参数	预设	描述
`$basepath`	必要	要建立新目录的位置
`$name`	必要	给新目录的名称
`$chmod`	`null`	给新目录的权限
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传布林 - PHP 函式 mkdir() 的输出

抛出 InvalidPathException 当基础路径不存在或不可写入。 FileAccessException 当基础路径不可写入。

範例

File::create_dir(DOCROOT, 'test', 0755);

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

读取一个档案并回传它（$as_string == true）或添加到输出（$as_string == false）。

静态是

参数

参数	预设	描述
`$path`	必要	要读取档案的位置
`$as_string`	`false`	让它在 false 时使用 readfile()，或在 `true` 时使用 file_get_contents()
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传整数｜字串 - 回传位元组数当 $as_string 设为 false，或档案的内容做为一个字串当它设为 true。

抛出 InvalidPathException 当档案不存在。

範例

// 回传 'Contents for file.' 如果你在 File::create() 的範例中建立该档案
$file_content = File::read(DOCROOT.'test.txt', true);

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

读取目录内容进入一个阵列。

静态是

参数

参数	预设	描述
`$path`	必要	要读取的目录位置
`$depth`	`0`	子目录要重现多深：0 是无限、 1 是只有目前目录或指定数字。
`$filter`	`null`	要读取档案的过滤器：`array()` 全部，或 `null` 全部但除了隐藏。
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传阵列 - 一个有子目录在上的自然字母排序的阵列。目录有一个带阵列值的字串键（或 false 当因为 $depth 限制而没读取时）以及带档案名称做为值的档案整数索引。所有目录有一个目录分隔符做为前缀。

抛出 InvalidPathException 当路径不是目录。 FileAccessException 当路径不可读取。

範例

// 读取一个目录
$contents = File::read_dir(DOCROOT);

// 有限制深度的读取
$contents = File::read_dir(DOCROOT, 2);

// 有自订规则的读取
$contents = File::read_dir(DOCROOT, 0, array(
	'!^\.', // 不要隐藏档案／目录
	'!^private' => 'dir', // 不要 private 目录
	'\.png$' => 'file', // 只取得 png
	'\.css$' => 'file', // 或 CSS 档案
	'!^_', // 排除任何以底线开头的。
));

/**
 * 正如你在上面可以看到的，
 * 你可以制定目录或档案的规则，
 * 透过在规则后面指定
 * 添加 "=> 'file'" 或 "=> 'dir'"。
 */

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

更新一个档案。

静态是

参数

参数	预设	描述
`$basepath`	必要	要更新的档案位置
`$name`	必要	档案名称。如果它不存在，它将被建立
`$contents`	`null`	想要放进档案的内容
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 true

抛出 InvalidPathException 当基础路径不是一个目录或不可写入。 FileAccessException 当没有写入权限。

範例

File::update(DOCROOT, 'test.txt', 'New contents for file.');

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

附加到一个存在的档案。

静态是

参数

参数	预设	描述
`$basepath`	必要	要附加的档案位置
`$name`	必要	档案名称。该档案必须存在
`$contents`	`null`	想要添加的档案
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 true

抛出 InvalidPathException 当基础路径不是一个目录或不可写入。 FileAccessException 当档案不存在。

範例

File::append(DOCROOT, 'test.txt', 'Additional contents for file.');

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

重新命名或移动一个目录或档案。

静态是

参数

参数	预设	描述
`$path`	必要	要重新命名的档案或目录位置
`$new_path`	必要	档案或目录的新名称
`$source_area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）
`$target_area`	`null`	要使用的选择性 Area 物件如果 $source_area 不包含 $new_path，预设是主要配置（更多资讯请见进阶用法）

回传 布林 rename() 的结果

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当档案类型不允许。

範例

// 重新命名 'test.txt' 为 'newname.txt'，并移动它到一个子目录
File::rename(DOCROOT.'test.txt', DOCROOT.'folder/newname.txt');

// 使用单一区域重新命名
File::rename(DOCROOT.'one.jpg', DOCROOT.'final.jpg', 'docroot');

// 在两个限制的区域之间移动并重新命名
File::rename(APPPATH.'tmp/file.jpg', DOCROOT.'folder/image.jpg', 'tmp', 'public');

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

File::rename 的别名

静态是

参数

参数	预设	描述
`$path`	必要	要重新命名的档案或目录位置
`$new_path`	必要	档案或目录的新名称
`$source_area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）
`$target_area`	`null`	要使用的选择性 Area 物件如果 $source_area 不包含 $new_path，预设是主要配置（更多资讯请见进阶用法）

回传 布林 rename() 的结果

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当档案类型不允许。

範例

File::rename(DOCROOT.'/dirname', DOCROOT.'/newdirname');

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

複製一个档案。

静态是

参数

参数	预设	描述
`$path`	必要	要複製的档案位置
`$new_path`	必要	要複製到，包含档案名称，的完整路径
`$source_area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）
`$target_area`	`null`	要使用的选择性 Area 物件如果 $source_area 不包含 $new_path，预设是主要配置（更多资讯请见进阶用法）

回传 布林 copy() 的结果

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当档案类型不允许。 InvalidPathException 当来源路径不是一个档案。 FileAccessException 当目标档案已存在。

範例

// 从 DOCROOT 複製档案 'test.txt' 到一个子目录
File::copy(DOCROOT.'test.txt', DOCROOT.'folder/test.txt');

// 使用单一区域複製
File::copy(DOCROOT.'one.jpg', DOCROOT.'img/one.jpg', 'public');

// 在两个限制的区域之间複製
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)

複製一个目录。

静态是

参数

参数	预设	描述
`$path`	必要	要複製的目录位置
`$new_path`	必要	要複製到的路径
`$source_area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）
`$target_area`	`null`	要使用的选择性 Area 物件如果 $source_area 不包含 $new_path，预设是主要配置（更多资讯请见进阶用法）

回传 null

抛出 OutsideAreaException 当路径不在档案区域内。 InvalidPathException 当来源路径不是一个目录。 FileAccessException 当目标目录已存在。

範例

File::copy_dir(DOCROOT.'/test', DOCROOT.'/newname');

delete($path, $area = null)

删除一个档案。

静态是

参数

参数	预设	描述
`$path`	必要	要删除的档案位置
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 布林 unlink() 的结果

抛出 OutsideAreaException 当路径不在档案区域内。 InvalidPathException 当来源路径不是一个档案。

範例

File::delete(DOCROOT.'/test.txt');

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

删除一个目录。

静态是

参数

参数	预设	描述
`$path`	必要	要删除的目录位置
`$recursive`	true	是否也删除子目录的内容
`$delete_top`	true	当为空时是否删除父层目录自身
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 布林 unlink() 的结果，或 true 当不删除子目录内容

抛出 OutsideAreaException 当路径不在档案区域内。 InvalidPathException 当来源路径不是一个目录。 FileAccessException 当在删除过程发生错误。

範例

File::delete_dir(DOCROOT.'/my_dir');

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

开启一个档案并锁定它。

静态是

参数

参数	预设	描述
`$path`	必要	要开启的档案位置
`$lock`	true	当档案开启是否锁定。
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 资源，档案资源

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当档案不能被锁定。

範例

$resource = File::open_file(DOCROOT.'/my_dir/text.txt');

close_file($resource, $area = null)

关闭一个档案并解锁它。

静态是

参数

参数	预设	描述
`$resource`	必要	开启的档案资源
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传 布林 如果有使用锁。

範例

$resource = File::open_file(DOCROOT.'/my_dir/text.txt');
// 对该资源做点什幺
File::close_file($resource);

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

为所给档案取回一个档案处理程序。阅读更多关于处理程序。

静态是

参数

参数	预设	描述
`$path`	必要	到要被包在一个处理程序中的档案或目录的路径
`$config`	array()	选择性的配置阵列
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传回传一个新的档案处理程序物件。

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当副档名不允许。

範例

$handler = File::get(DOCROOT.'/my_dir/text.txt');

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

检索一个档案的公开 URL。URL 必须被设定在基础配置或所使用区域的区域配置。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$config`	array()	选择性的配置阵列
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传档案的公开 URL。

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当副档名不允许。

範例

$url = File::get_url(DOCROOT.'/my_dir/text.txt');
// 回传一些东西像：http://mydomain.com/mydir/text.txt

get_permissions($path, $area = null)

检索档案或目录的八进位制权限。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传八进位制的档案权限

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当副档名不允许。

範例

$permissions = File::get_permissions(DOCROOT.'/my_dir/text.txt');
// 回传 "0755"

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

检索档案或目录的建立或修改时间。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$type`	'modified'	要检索的时间类型。必须是 modified 或 created
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传档案建立／修改的 UNIX 时间戳记

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当副档名不允许。

範例

$permissions = File::get_time(DOCROOT.'/my_dir/text.txt', 'created');

get_size($path, $area = null)

检索一个档案的大小（位元组）。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传档案大小（位元组）。

抛出 OutsideAreaException 当路径不在档案区域内。 FileAccessException 当副档名不允许。 InvalidPathException 当档案找不到。

範例

$filesize = File::get_size(DOCROOT.'/my_dir/text.txt');

file_info($path, $area = null)

检索一个关于指定档案资讯的阵列。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）

回传一个有档案资讯项目的阵列。该阵列将包含路径、档案名称及副档名资讯、档案大小及权限、建立与最后修改时间戳记、侦测的 MIME 类型及档案的字符集。

抛出 InvalidPathException 当档案找不到。 InvalidArgumentException 当档案资讯不能被测定。

範例

$filesize = File::file_info(DOCROOT.'/my_dir/text.txt');

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

输出一个档案、内嵌或做为一个下载附件。。

静态是

参数

参数	预设	描述
`$path`	必要	档案路径
`$name`	`null`	覆写档案的预设档名
`$mime`	`null`	覆写档案的预设 MIME 类型
`$area`	`null`	要使用的区域物件，预设是主要配置（更多资讯请见进阶用法）
`$delete`	`false`	在下载之后是否要删除档案
`$disposition`	`'attachment'`	是否下载或内嵌输出。接受 'attachment' 或 'inline'，预设为 'attachment'。

回传没有 - 此方法在初始化下载后结束。

抛出 InvalidPathException 当档案不存在。 InvalidArgumentException 如果该档案没有档案资讯可以被检索。 FileAccessException 当档案无法被开启读取。

範例

// 下载档案
File::download(DOCROOT.'/my_dir/text.txt', 'newfile.txt');

// 输出一个内嵌图像，用来做为一个 <img> 标籤来源
File::download(DOCROOT.'/img/image.jpg', null, 'image/jpeg', null, false, 'inline');

请注意，当你呼叫此方法，它不会立即下载档案。它会在档案下载后安排一个 shutdown 事件，并终止该指令码。这确保了所有 Fuel shutdown 函式，像更新 session，会正常执行。