アップロードライブラリ

Ziu 付属のアップロードライブラリです。HTTPリクエストで送られるファイルを扱う機能を提供します。

設定
使い方
メソッドリファレンス

設定

アップロードライブラリを利用するための設定を行ないます。

単体で利用の設定方法

本アップロードライブラリは、単体で使用することができます。

$upl = new Upload;
$upl->config(array(
    'save_path'     => '/var/www/vhosts/sample.com/htdocs/upload',
    'save_filename' => 'image_:id.:ext',
))->files('upl_image', '画像')->save(); // 'save_path' に保存

Ziu で利用の設定方法

Ziu での利用では、ロジッククラスやユニットクラスで主に利用します。

$upl = lib('upload')->config(array(
    'save_path'     => ZIU_DISPATCH_PATH . DS . 'upload',
    'save_filename' => 'image_:id.:ext',
))->files('upl_image', '画像')->save(); // 'save_path' に保存

項目	型	初期値	説明
save_path	string	なし	ファイル保存先パスを指定します。
save_subdir	string	なし	保存先パス配下のサブフォルダ名を指定します。
save_tmpdir	string	なし	保存先パス配下の一時保存フォルダ名を指定します。
save_tmpdir_prefix	string	`_tmp_`	一時保存フォルダが自動生成される場合のプレフィックスを指定します。
auto_clean_tmpdir	boolean	TRUE	一時保存フォルダ自動クリーニングフラグを指定します。注1) 参照
clean_limit_time	integer	3600	自動クリーニング対象となるまでの有効時間を秒で指定します。
save_overwrite	boolean	TRUE	ファイルの上書きフラグを指定します。ファイルが存在した場合上書きします。
path_chmod	integer	0777	作成するフォルダパーミッションを指定します。
file_chmod	integer	0666	保存するファイルパーミッションを指定します。
save_filename	string	なし	保存ファイル名を指定します。デフォルトは`$_FILES['name']`を使用します。[特殊キーワード]を使用して置換することができます。注2) 参照
required	boolean	FALSE	アップロードファイルの必須フラグを指定します。
max_size	integer	0	ファイルサイズの上限値を指定します。 (0 は上限なし)
max_name	integer	0	ファイル名文字列長さの上限値を指定します。 (0 は上限なし)
accept_ext	string	なし	許可する拡張子をカンマ区切りで指定します。(ホワイトリスト方式)
except_ext	string	なし	拒否する拡張子をカンマ区切りで指定します。(ブラックリスト方式)
accept_type	string	なし	許可するファイルタイプをカンマ区切りで指定します。(ホワイトリスト方式)
except_type	string	なし	拒否するファイルタイプをカンマ区切りで指定します。(ブラックリスト方式)
accept_mime	string	なし	許可するMIMEをカンマ区切りで指定します。(ホワイトリスト方式)
except_mime	string	なし	拒否するMIMEをカンマ区切りで指定します。(ブラックリスト方式)
error_message	array	なし	エラーメッセージを指定します。注3) 参照

注1) 一時保存フォルダの自動クリーニング
files() メソッドの実行タイミングで clean_limit_time を超過した一時保存フォルダを削除してクリーニングします。
一時保存フォルダには、save_tmpdir_prefix で指定したプレフィックスの利用が必要です。(デフォルトでは利用)

注2) 保存ファイル名の[特殊キーワード]
アップロード$_FILES['upl_image']を例として示します。
:org - $_FILES['upl_image']['name']の値
:key - upl_image のキー文字列
:id - $_FILES['upl_image']でアップロードしたファイル番号 (0からカウントアップ)
:ext - アップロードファイル拡張子
:pid - サーバープロセスID
:date - サーバー日付(Ymd)
:time - サーバー時間(His)
:md5 - ファイルMD5

例) 'save_filename' => 'image_:id.:ext',

注3) エラーメッセージ
エラーメッセージは配列で指定します。変更の場合は未変更を含む全てのメッセージ指定が必要です。

'error_message' => array(
    UPLOAD_ERR_OK         => '',  
    UPLOAD_ERR_INI_SIZE   => 'アップロードに失敗しました。',  
    UPLOAD_ERR_FORM_SIZE  => 'アップロードに失敗しました。',  
    UPLOAD_ERR_PARTIAL    => 'アップロードに失敗しました。',  
    UPLOAD_ERR_NO_FILE    => 'アップロードに失敗しました。',  
    UPLOAD_ERR_NO_TMP_DIR => 'アップロードに失敗しました。',  
    UPLOAD_ERR_CANT_WRITE => 'アップロードに失敗しました。',  
    UPLOAD_ERR_EXTENSION  => 'アップロードに失敗しました。',  
    UPLOAD_ERR_VALID_SIZE => 'ファイルサイズが超過しています。',  
    UPLOAD_ERR_VALID_NAME => 'ファイル名が長すぎます。',  
    UPLOAD_ERR_VALID_EXT  => '不正な拡張子です。',  
    UPLOAD_ERR_VALID_TYPE => '不正なファイルタイプです。',  
    UPLOAD_ERR_VALID_MIME => '不正なMIMEタイプです。',  
    UPLOAD_ERR_MOVE_FILE  => 'アップロードに失敗しました。',  
    UPLOAD_ERR_DUPLICATE  => 'アップロードに失敗しました。',  
    UPLOAD_ERR_MKDIR      => 'アップロードに失敗しました。',
),

使い方

アップロードライブラリはリクエストライブラリ／フォームライブラリと併せてよく利用します。

初期設定
一時フォルダ名を取得(ライブラリ内部でもバインドされる)し、アップロード情報を設定します。

$upl = lib('upload');
$tmp_dir = $upl->use_save_tmpdir();

$upl->config(array(
    'save_path'     => ZIU_DISPATCH_PATH . DS . 'upload',
    'save_filename' => 'image_:id.:ext',
    'accept_ext'    => 'jpg',
    'accept_mime'   => 'image/jpeg,image/jpg,image/pjpeg',
))->files('upl_image', '画像');

リクエストライブラリ
POSTリクエストの取得とビューテンプレートで利用するフォームライブラリにバインドする変数形成を行ないます。

$r = lib('request');
$id = $r->post('content_id');
$req = array(
    'image'     => $r->post('image'),
    'tmp_image' => $r->post('tmp_image'),
    'tmp_dir'   => $r->post('tmp_dir', $tmp_dir),
    'temp_uri'  => $r->post('temp_uri', uri('upload/' . $tmp_dir)),
    'real_uri'  => $r->post('real_uri', empty($id) ? '' : uri('upload/' . $id)),
);

フォームライブラリ
ビューテンプレートで利用する file() メソッドの連携モード file_extend_mode を有効にします。

render_set(array(
    'f' => lib('form')->config(array('file_extend_mode' => TRUE))->values($req)
));

ビューテンプレート (入力)
ファイル送信する <input type="file"> タグを表示します。

$f->open('<確認ページURL>', 'file');
$f->file('image');
$f->file_preview('img', 'image', 'real_uri', 'temp_uri');
$f->close();

ビューテンプレート (確認)
一時保存フォルダにアップロードされたファイルをフォームライブラリを利用して表示します。

$f->open('<登録ページURL>');
$f->file_preview('img', 'image', 'real_uri', 'temp_uri');
$f->close();

バリデーション
アップロードしたファイルを初期設定に準じたチェックを行ないます。エラーが発生した場合にエラーメッセージを取得することができます。

if ($upl->validate() === FALSE) {
    $error = $upl->get_errors('[:label :id] :state(code: :code)');
}

確認処理 (ファイル保存とファイル情報の取得)
一時保存フォルダにファイル保存し、ビューテンプレートで利用するフォームライブラリにバインドする変数形成を行ないます。

$upl->save();
$file = $upl->get_file(0);
$req['tmp_image'] = $file['error'] ? $req['tmp_image'] : $file['save_filename'];
lib('form')->values($req);

確認ページがないパターンでは、確認処理／登録処理を合わせた形で調節します。

登録処理 (保存フォルダ移動)
データベース登録とフォルダにファイル保存(一時保存フォルダのリネーム)し、完了ページへリダイレクトします。

$data['image'] = empty($req['tmp_image']) ? $req['image'] : $req['tmp_image'];
$dao->insert($data);
$upl->move_tmpdir_to($dao->last_insert_id());
redirect_to('<完了ページURL>?refer=' . $this->req['refer']);

メソッドリファレンス

アップロードライブラリのメソッドリファレンスです。

設定メソッド
- config() : 初期設定
- use_save_tmpdir() : 一時保存フォルダの指定
- files() : エレメント名の指定
アップロード処理メソッド
- validate() : バリデーションの実行
- save() : ファイルの保存
- get_file() : ファイル情報の取得
フォルダ移動／削除メソッド
- move_subdir_to() : サブフォルダの移動
- move_tmpdir_to() : 一時保存フォルダの移動
- remove_subdir() : サブフォルダの削除
- clean_subdir_of() : 一時保存フォルダのクリーニング
エラーメッセージメソッド
- get_message() : エラーメッセージの取得(キーワードなし)
- get_error() : エラーメッセージの取得
- get_errors() : 全てのエラーメッセージの取得

設定メソッド

config(array $config)

ファイルアップロードを初期設定をします。

戻り値

型 : object Upload

引数値

項目	型	内容
$config	array	設定を配列で指定

$config に指定する設定項目については、設定を参照して下さい。

例) lib('upload')->config(array('save_path' => ZIU_DISPATCH_PATH . DS . 'upload'));

use_save_tmpdir($tmpdir = NULL)

一時保持ディレクトリを指定します。

戻り値

型 : string

引数値

項目	型	内容
$tmpdir	string	フォルダ名

$tmpdir 未指定の場合一時フォルダ名を自動生成します。(通常はデフォルトを利用)

例) $tmpdir = $upl->use_save_tmpdir();

files($name, $label)

アップロード対象の $_FILES エレメント名を指定します。

戻り値

型 : object Upload

引数値

項目	型	内容
$name	string	エレメント名
$label	string	ラベル名

例) $upl->files('upl_image', '画像');

▲リファレンスTOP

アップロード処理メソッド

validate(array $config = array())

アップロードファイルのバリデーションを実行します。

戻り値

型 : boolean

引数値

項目	型	内容
$config	array	一時的な追加設定

例) $res = $upl->validate() ? 'OK' : 'NG';

save()

アップロードファイルを保存します。

戻り値

型 : void

引数値

なし

例) $upl->save();

get_file($id = NULL)

アップロードファイル情報を取得。

戻り値

型 : array

引数値

項目	型	内容
$id	integer	ファイル番号

$id 未指定の場合、全てのファイル情報を取得します。
ファイル番号は対象エレメント名ごとに 0 からカウントされ、単ファイルの場合でもファイル番号は 0 になります。

例) $upl->get_file(0);

▲リファレンスTOP

フォルダ移動／削除メソッド

move_subdir_to($subdir, $remove = TRUE)

初期設定で指定したサブフォルダを任意のフォルダ名にリネームします。

戻り値

型 : void

引数値

項目	型	内容
$subdir	string	フォルダ名
$remove	boolean	既存フォルダ削除フラグ

$remove は更新時に必要な削除機能になります。

例) $upl->move_subdir_to($dest_content_id);

move_tmpdir_to($subdir, $remove = TRUE)

一時保存フォルダを任意のフォルダ名にリネームします。

戻り値

型 : void

引数値

項目	型	内容
$subdir	string	フォルダ名
$remove	boolean	既存フォルダ削除フラグ

$remove は更新時に必要な削除機能になります。

例) $upl->move_tmpdir_to($new_content_id);

remove_subdir()

初期設定で指定したサブフォルダを削除します。

戻り値

型 : void

引数値

なし

例) $upl->remove_subdir();

clean_subdir_of($subdir, $time = NULL)

サブフォルダをクリーニングします。

戻り値

型 : void

引数値

項目	型	内容
$subdir	string	フォルダ名
$time	integer	クリーニング対象時間(秒)

$subdir ワイルドカードを利用できます。
$time クリーニング対象時間を経過したフォルダが削除されます。

例) $upl->clean_subdir_of();

▲リファレンスTOP

エラーメッセージメソッド

get_message($id = NULL)

バリデーションのエラーメッセージの内容を取得します。

戻り値

型 : mixed

引数値

項目	型	内容
$id	integer	ファイル番号

$id が未指定の場合は、全てのエラーメッセージが返されます。

例) $upl->get_message(0);

get_error($id, $format, $pre = '', $suf = "\n")

メッセージキーワードを用いた、バリデーションのエラーメッセージを取得します。

戻り値

型 : string

引数値

項目	型	内容
$id	integer	ファイル番号
$format	string	メッセージフォーマット
$pre	string	メッセージプレフィックス
$suf	string	メッセージサフィックス

$format は [メッセージキーワード] を指定して置換えすることができます。
[メッセージキーワード]
:label - ラベル名
:id - ファイル番号
:state - エラーステート文
:code - エラーコード番号

例) $error = $upl->get_error(0, '[:label :id] :state(code: :code)');

get_errors($format, $pre = '', $suf = "\n")

メッセージキーワードを用いた、全てのバリデーションエラーメッセージを取得します。

戻り値

型 : string

引数値

項目	型	内容
$format	string	メッセージフォーマット
$pre	string	メッセージプレフィックス
$suf	string	メッセージサフィックス

$format については get_error() を参照して下さい。

▲リファレンスTOP

アップロード ライブラリ

設定

単体で利用の設定方法

Ziu で利用の設定方法

使い方

メソッドリファレンス

設定メソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

アップロード処理メソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

フォルダ移動／削除メソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

戻り値

引数値

エラーメッセージメソッド

戻り値

引数値

戻り値

引数値

戻り値

引数値

アップロードライブラリ