File 类別

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，会正常执行。