ハンドラ

導入

Fuel ではディレクトリとファイルをオブジェクトでラップ出来ます。これによって、 オブジェクト指向ベースでファイルシステムのアイテム (ファイルとディレクトリ) にアクセスし、またそれを変更することが出来ます。

File クラス (あるいはファイルエリア) によって得られたオブジェクトのことを ファイルハンドラ といいます。 Fuel では 2 つの核となるファイルハンドラがあります: ファイルハンドラ と ディレクトリハンドラ です。 おわかりのように、それらハンドラに関するクラスは、それぞれファイルとディレクトリを扱います。

トピックス

使用法

ハンドラに関するヘルパークラスは、それぞれメソッド一式を持っています。 それらクラスのメソッドを使ってオブジェクトにラップされたファイルあるいはディレクトリを処理することが出来ます。 以下、File::get を使った幾つかの例を示します。 

 // まずファイルを取得します
$file = \File::get(DOCROOT.'/here_is_my/textfile.txt');

ファイルハンドラを得ることができたので、以下、なにか動作するメソッドを使います。

// リネームします。
$file->rename('new_name');

// ファイルの中身を取得します
$content = $file->read();

// 元々のファイル名にリネームし直します。
$file->rename('textfile');

以上の例でわかるように、ファイルをリネームする時、そのハンドラを再度取得する必要はありません。 同じオブジェクトを繰り返し再利用出来ます。ファイルを削除するか、値を unset する時まで再利用は可能です。

ファイルハンドラ

ファイルハンドラは、基本的なファイルの操作を取り扱います。以下の例では、 $handler 変数が取得されたハンドラである、とします。 ハンドラを得る方法を知りたい場合は 使用法のセクション を参照してください。

forge($path, $config = array(), $area = null, $content = array())

forge メソッドは生成した File_Handler_File オブジェクトを返します。

静的 はい
パラメタ
パラメータ 規定値 説明
$path 必須 ファイルのパス
$config array() オプションで、config の配列を書けます。
$area null File_Area インスタンス
$content 配列 無視
返り値 生成した File_Handler_File オブジェクトを返します。
例 
$handler = File_Handler_File::forge('path/to/file.txt', $config_array, $my_file_area);

read($as_string = false)

read メソッドは File::read のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$as_string false true なら、readfile() のかわりに file_get_contents() を使います。
返り値 IO か文字列 (ファイルの中身) を返します。
例 
$file_content = $handler->read(true);

rename($new_name, $new_extension = false)

rename メソッドは File::rename のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_name 必須 新しいファイル名
$new_extension false 新しいファイル拡張子
返り値 rename() が返す boolean
例 
$handler->rename('new_name');

move($new_path)

move メソッドは File::move のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_path 必須 新しいディレクトリパス。有効なパスでなければなりません
返り値 rename()が返すboolean。
例 
$handler->move(DOCROOT.'/new/parent/directory/');

copy($new_path)

copy メソッドは File::copy のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_path 必須 コピー先の新しいディレクトリパス。有効なパスでなければなりません
返り値 copy() が返す boolean
例 
$handler->copy(DOCROOT.'/directory/');

update($new_content)

update メソッドは File::update のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_content 必須 新しいファイルコンテント
返り値 成功すればtrue
例 
$handler->update('the new content');

delete()

delete メソッドは File::delete のショートカットです。

静的 いいえ
返り値 unlink()が返すbool。
例 
$handler->delete();

get_url()

get_url メソッドは File::get_url のショートカットです。

静的 いいえ
返り値 public url
例 
$url = $handler->get_url();

get_permissions()

get_permissions メソッドは File::get_permissions のショートカットです。

静的 いいえ
返り値 8進数のファイルパーミッション
例 
$permissions = $handler->get_permissions();

get_time($type = 'modified')

get_time メソッドは File::get_time のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$type 'modified' 必要な時刻が返されます。created か modified の 2 つのみ利用出来ます。
返り値 ファイル作成時、変更時のタイムスタンプ。
例 
$created_at = $handler->get_time('created');

$modified_at = $handler->get_time('modified');
// 省略も可能
$modified_at = $handler->get_time();

get_size()

get_time メソッドは File::get_size のショートカットです。

静的 いいえ
返り値 The file size in bytes
例 
$file_size = $handler->get_size();

ディレクトリハンドラ

ディレクトリハンドラは、ディレクトリを大元のところから対話的に取り扱います。以下の例では、 $handler が取得されたハンドラである、とします。 ハンドラを得る方法を知りたい場合は 使用法のセクション を見てください。

forge($path, $config = array(), $area = null, $content = array())

forge メソッドは生成された File_Handler_Directory オブジェクトを返します。

静的 はい
パラメタ
パラメータ 規定値 説明
$path 必須 ディレクトリのパス
$config array() オプションで、config の配列を書けます。
$area null File_Area インスタンス
$content array ディレクトリのコンテント
返り値 生成した File_Handler_File オブジェクトが返ります。
例 
$handler = File_Handler_Directory::forge('path/to/dir');

read($depth = 0, $filters = null)

read メソッドは File::read_dir のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$depth 0 再帰的なディレクトリの深さ。1 なら現在のカレントのみ。0 あるいはそれ以下なら無限に再帰
$filters null 部分的な正規表現配列。デフォルトは配列なし。
返り値 ディレクトリコンテントの配列を返します。
例 
$dir_contents = $handler->read();

rename($new_name)

rename メソッドは File::rename_dir のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_name 必須 新しいディレクトリ名
返り値 rename() が返す boolean
例 
$handler->rename('new_name');

move($new_path)

move メソッドは File::move のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$new_path 必須 新しいディレクトリパス。有効なパスでなければなりません
返り値 rename()が返すboolean。
例 
$handler->move(DOCROOT.'/new/parent/directory/');

copy($new_path)

copy メソッドは File::copy_dir のショートカットです。

静的 いいえ
パラメタ 　
パラメータ 規定値 説明
$new_path 必須 コピー先の新しいディレクトリパス。有効なパスでなければなりません。
返り値 copy() が返す boolean
例 
$handler->copy(DOCROOT.'/directory/');

delete($recursive = true, $delete_top = true)

delete メソッドは File::delete_dir のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$recursive true サブディレクトリのコンテンツも消去するかどうか。
$delete_top true もし空ならば、親ディレクトリを消去するかどうか。
返り値 成功すると true
例 
$handler->delete();

get_permissions()

get_permissions メソッドは File::get_permissions のショートカットです。

静的 いいえ
返り値 8 進数のディレクトリパーミッション
例 
$permissions = $handler->get_permissions();

get_time($type = 'modified')

get_time メソッドは File::get_time のショートカットです。

静的 いいえ
パラメタ
パラメータ 規定値 説明
$type 'modified' 必要な時刻が返されます。created か modified の 2 つのみ利用出来ます。
返り値 ディレクトリ作成時、変更時のタイムスタンプ。
例 
$created_at = $handler->get_time('created');

$modified_at = $handler->get_time('modified');
// 次のように省略可能
$modified_at = $handler->get_time();

ハンドラを書く

以上述べて来たように、Fuel はあらかじめ設定されたハンドラを 2 つ持っています。 ディレクトリとファイルに関するハンドラです。これに加えて、ハンドラを書くことで、ファイルタイプ毎の動作を変化させたり新しい機能を付け加えることができます。 たとえば、csv ファイルを読み込み時に自動パースしたい、あるいは画像ファイルから画像オブジェクトを取得したい、というようなことです。

どのように書くか...

ハンドラは File Handler クラス (\File_Handler_File) の拡張クラスです。 次に例を示します。 

<?php

class File_Handler_XML extends \File_Handler_File
{

	/**
	 * ハンドラにおけるファイル内容処理の仕方を定めたメソッドを読み込む
	 */
	public function read()
	{
		return simplexml_load_file($this->path);
	}
}

/* End of file xml.php */

上記の $this->path に留意ください。このプロパティは、ファイルの移動やリネーム時にも、カレントファイルのパスを常に保持します。

ハンドラに付加する...

ファイルの config に付け加えることで、ファイルハンドラを割り当てることが出来ます。 ベースの config に加えれば、ある拡張子をもつ全てのファイルが、得たいハンドラとして取得されます。 エリア内で使いたい場合は、エリアの config に付け加えれば エリアベースのハンドラとして割り付けることも出来ます。 

// In app/config/file.php

'base_config' => array(
	'file_handlers' => array(
		'csv' => 'File_Handler_Csv',
	),
),

'areas' => array(
	'my_area' => array(
		'file_handlers' => array(
			'xml' => 'File_Handler_XML',
		),
	),
),