Upload クラス

upload クラスは、アプリケーションにアップロードされたファイルを安全に処理する事ができます。 アップロードを様々な方法でフィルタできます。目的のファイル名がどんな名前であるべきか、ファイルサイズやファイル名の長さでフィルタするか、等を定義できます。

アップロードされたファイルの配列

アップロードされたファイルの情報はすべて、Upload クラス内の多次元配列に格納されます。 ファイル毎に、以下のフィールドが定義された配列が作成されます。

Key 型 説明
field string ファイルアップロードに使用されたフォームのフィールド名。フォームフィールドが (多次元の) 配列の場合は、 配列のキーをコロンで区切って追加します。 フィールドが "field[a][b][]" の場合は "field:a:b:0" と格納されます。
name string アップロードされたファイルの名前。
type string アップロードされたファイルの Mime-type。ブラウザが定義したもの。
mimetype string アップロードされたファイルの Mime-type。Upload クラスが判定したもの。 最新の 'mime magic' ファイルがインストールされている必要があります。 このファイルはすべての *nix プラットフォームにありますが、Windows プラットフォームにはありませんので、インストールが必要かもしれません。 mime-type が判定できなかった場合は、'type' の値と同じになります。
file string アップロードされたファイルの一時的な置き場所の完全修飾名。
filename string アップロードされたファイルのファイル名 (basename)
extension string アップロードされたファイルの拡張子
size integer アップロードされたファイルのバイト数。
error boolean アップロードに失敗した場合は true となり、errors 配列に原因が記述される。
errors array 配列を要素とする配列。それぞれ 'error' と 'message' の 2 つの値をもち、'error' にはエラーコード、'message' にはエラー文字列が記述される。

mime-type は最も限定されたものになることに注意してください。たとえば、ブラウザが MS-Word document であると主張し、mime-type が "application/octet-stream" と判定された場合、ブラウザの mime-type が使用されます。ブラウザの mime-type が間違っている場合や予想外だったとしてもです。 例えば、Microsoft .xlsx file が、"application/zip" と判定されるかもしれません。

save() メソッドを呼び出した後、この配列にはさらに 2 つのフィールドが追加されます。これらのフィールドは何が保存されたかの情報が記述されます。

Key 型 説明
saved_to string アップロードされたファイルが保存されている完全修飾パス。
saved_as string 保存されたファイルのファイル名。
errors array errors 配列 (と error 真偽値) は、save() メソッド呼び出し後に更新され、ファイルを保存する時に発生したエラーを記述します。

定義済みエラー定数

Upload クラスで定義されているエラー定数です。

Name 説明
UPLOAD_ERR_OK エラーが発生せず、ファイルが正常にアップロードされた。
UPLOAD_ERR_INI_SIZE ファイルサイズが php.ini の upload_max_filesize ディレクティブを超えた。
UPLOAD_ERR_FORM_SIZE ファイルサイズが HTML フォームの MAX_FILE_SIZE ディレクティブを超えた。
UPLOAD_ERR_PARTIAL ファイルが一部しかアップロードされなかった。
UPLOAD_ERR_NO_FILE ファイルがアップロードされなかった。このエラーのあるエントリは、アップロードされたファイル一覧が処理されるときにフィルタリングされます。
UPLOAD_ERR_NO_TMP_DIR 一時フォルダが無い。
UPLOAD_ERR_CANT_WRITE ディスクへの書き込みに失敗した。
UPLOAD_ERR_EXTENSION PHP の拡張モジュールがファイルのアップロードを中止した。どの拡張モジュールがファイルアップロードを中止させたのかを突き止めることはできません。 読み込まれている拡張モジュールの一覧を phpinfo() で取得すれば参考になるでしょう。
UPLOAD_ERR_MAX_SIZE ファイルサイズが、FuelPHP の設定で定義した最大サイズを超えた。
UPLOAD_ERR_EXT_BLACKLISTED ファイル拡張子が、FuelPHP の設定で定義したブラックリストに合致した。
UPLOAD_ERR_EXT_NOT_WHITELISTED ファイル拡張子が、FuelPHP の設定で定義したホワイトリストに無い。
UPLOAD_ERR_TYPE_BLACKLISTED ファイル拡張子が、FuelPHP の設定で定義したファイルタイプのブラックリストに合致した。
UPLOAD_ERR_TYPE_NOT_WHITELISTED ファイル拡張子が、FuelPHP の設定で定義したファイルタイプのホワイトリストに無い。
UPLOAD_ERR_MIME_BLACKLISTED ファイル拡張子が、FuelPHP の設定で定義した mime-type のブラックリストに合致した。
UPLOAD_ERR_MIME_NOT_WHITELISTED ファイル拡張子が、FuelPHP の設定で定義した mime-type のホワイトリストに無い。
UPLOAD_ERR_MAX_FILENAME_LENGTH ファイル名が、FuelPHP の設定で定義したファイル名の長さを超えた。
UPLOAD_ERR_MOVE_FAILED ファイルが、FuelPHP の設定で定義したパスに移動できなかった。パーミッションの問題の可能性があります。
UPLOAD_ERR_DUPLICATE_FILE 同名のファイルが既に存在するため、保存できなかった。

アップロード可能にするには、HTML <form> タグに enctype="multipart/form-data" が含まれていなければなりません。またフォームには タイプが "file" のフィールドが最低 1 つ含まれていなければなりません。そうしないと、アップロードは失敗し、Upload::process が例外を投げます。

使用例

// このアップロードのカスタム設定
$config = array(
	'path' => DOCROOT.'files',
	'randomize' => true,
	'ext_whitelist' => array('img', 'jpg', 'jpeg', 'gif', 'png'),
);

// $_FILES 内のアップロードされたファイルを処理する
Upload::process($config);

// 有効なファイルがある場合
if (Upload::is_valid())
{
	// 設定にしたがって保存する
	Upload::save();

	// モデルを呼び出してデータベースを更新する
	Model_Uploads::add(Upload::get_files());
}

// エラーを処理する
foreach (Upload::get_errors() as $file)
{
	// $file はファイル情報の配列
	// $file['errors'] は発生したエラーの内容を含む配列で、
	// 配列の要素は 'error' と 'message' を含む配列
}

is_valid()

is_valid メソッドは、バリデーションを通過したファイルがあるかどうかをチェックします。

静的 はい
パラメータ なし
返り値 boolean - バリデーションされたファイルがあれば true、無ければ false。
例 
// 保存したいファイルがあるか？
if (Upload::is_valid())
{
	Upload::save();
}

get_files($index = null)

get_files メソッドは、エラーの値が false である全てのファイルから成る多次元配列を返します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$index optional 配列の添字、またはフォームフィールド名。未指定の場合、バリデーションされた全てのファイルから成る配列を返します。 添字が有効でない場合や、エラーステータスが true のファイルを指定した場合は、例外が投げられます。
返り値 array
例 
// アップロードに成功したファイルの一覧を取得する
foreach(Upload::get_files() as $file)
{
	// ファイル情報を処理する
}

// 添字0を指定し、最初にアップロードされたファイルを取得する
if ( ! Upload::get_files(0))
{
	// 最初にアップロードされたファイルはアップロードに失敗しました。
}

get_errors($index = null)

get_errors エラーステータスが true である全てのファイルから成る多次元配列を返します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$index optional 配列の添字、またはフォームフィールド名。未指定の場合、有効でない全てのファイルから成る配列を返します。 添字が有効でない場合や、エラーステータスが false のファイルを指定した場合は、例外が投げられます。
返り値 array
例 
// エラーが発生したファイルの一覧を取得する
foreach(Upload::get_errors() as $file)
{
	// ファイル情報を処理する
}

// フィールド名を指定し、アップロードされたファイルを取得する
if (Upload::get_errors('new_image'))
{
	// <input type="file" name="new_image" /> で定義される
	// フォームフィールドが 'new_image' のファイルのアップロード時にエラーが発生しました。
}

全てのフォームのアップロードフィールドが送信されることに注意してください。たとえそれらがオプションであったとしてもです。空欄のままのフィールドは、 アップロードされたファイルの配列に、エラーコード Upload::UPLOAD_ERR_NO_FILE の空エントリが記述されます。 エラーを処理するとき、まずエラーコードをチェックし、その後、エラー以外のフィールドを使用してください。

register($event, $callback)

register メソッドは、特定のアップロードイベントにコールバックを登録します。 また、あなたの独自のコードに process() と save() メソッドを追加できます。

静的 はい
パラメータ
パラメータ デフォルト 説明
$event 必須 登録したいコールバックイベント名。'validate'、'before'、'after' から選択する。
$callback 必須 有効な PHP コールバック関数。関数、動的／静的メソッド、クロージャが可能。
返り値 boolean - コールバックが登録されていれば true、登録に失敗していれば false。
例 
// before コールバックに、クロージャ登録
Upload::register('before', function (&$file) {
	if ($file['error'] == Upload::UPLOAD_ERR_OK)
	{
		switch($file['extension'])
		{
			case "jpg":
			case "png":
			case "gif":
				// images サブディレクトリに保存する
				$file['file'] .= 'images/';
			break;

			case "css":
				// css サブディレクトリに保存する
				$file['file'] .= 'css/';
			break;

			case "js":
				// javascript サブディレクトリに保存する
				$file['file'] .= 'js/';
			break;

			default:
				// それ以外の場合はパスを変更しない
		}
	}
});

'validate' コールバックを使用したい場合は、Upload::process() を呼び出す前に登録するようにしてください。 'auto_process' 設定にしている場合は、Upload クラスを使用するとすぐに Upload::process() が呼び出されます。 つまり、実行時にコールバックを定義したい場合は、この設定にすることはできません。

コールバックは、FuelPHP\Upload\File オブジェクトをパラメータとして受け取ります。エントリは参照で渡されるので、 コールバックがエントリを変更することができます。後方互換のために配列としてアクセスすることができますが、 バージョン < 1.6 から 1.6+ へ移行する場合、コールバックに渡される値をチェックしてください。 全ての属性が 1.6 以前と同じではないからです。
コールバック関数が整数を返す場合、アップロードされたファイルのエラーコードを修正する、とみなされます。 その他の返り値は無視されます。

注意: コールバックで $file 配列の内容を変更する場合、情報が有効のままであるようにする必要があります。 Upload クラスは再チェックしません。'file' パスについては例外で、 コールバック実行後に必要ならばチェックして作成されます。

process($config = array())

process メソッドは、アップロードされた全てのファイルの情報を処理し、 フォームフィールド名の並びを統一し、 ファイルとその mimetype の追加情報を取得し、 ファイルをバリデーションします。

静的 はい
パラメータ
パラメータ デフォルト 説明
$config optional 設定アイテムの配列。設定ファイルに定義されている設定を上書きできる。
返り値 void
Throws FuelException。ファイルアップロード試行が検出されなかったとき ("Enctype" や type="file" のフィールドがないフォーム)
例 
// アップロードされたファイルを処理する
// 最大サイズを 10Kb にセットし、重複ファイルを上書きする
Upload::process(array(
	'max_size'    => 10240,
	'auto_rename' => false,
	'overwrite'   => true
));

このメソッドを使用する場合は、設定で auto_process を無効にして、2 回処理するのを回避してください。

save( ... )

save メソッドは、バリデーションされた全てのファイルを指定したパスに保存します。

静的 はい
パラメータ
パラメータ デフォルト 説明
$integer optional get_files() が返す配列のキー。アップロードされたファイルのセットから、1 つのファイルを保存することができます。
$array optional get_files() が返す配列のキーの配列。アップロードされたファイルのセットから、複数のファイルを保存することができます。
$string optional ファイルを保存するパス。設定で指定したパスや、process() メソッドが呼び出された時の $config を上書きします。

これらのパラメータは全てオプションで、パラメータの順序は定められていません。しかし、$integer と $array はどちらかだけを指定してください。双方を指定した場合、最後に指定したものを使用します。
返り値 void
例 
// バリデーションされた全てのファイルを保存する
Upload::save();

// 最初にアップロードされたファイルだけを保存する
Upload::save(0);

// 1 つ目、2 つ目、4 つ目のファイルを保存する
Upload::save(0, 1, 3);

// バリデーションされた全てのファイルを別の場所に保存する
$arr = Upload::get_files();
Upload::save(DOCROOT.'assets', array_keys($arr));

// これらのファイルのエラーを処理する
foreach (Upload::get_errors() as $key => $file)
{
	// ここでエラーを処理する
}