登录
目录
当前位置： 首页 > 文档资料 > FuelPHP 中文文档 >

Upload 用法 - 类別

优质
小牛编辑
120浏览
2023-12-01

Upload 类别可以安全地处理被上传到应用程序的档案。 它能让你用不同的方式过滤上传、定义目标档案名称应该像怎样、或过滤档案名称的大小或长度。

上传档案阵列

每个上传档案的资讯被储存在 Upload 类别中的一个多维阵列。 对于每个档案，每个被定义的阵列有下列栏位：

键类型描述
field字串被用来上传档案的表单栏位名称。如果该表单栏位是一个（多维）阵列， 该阵列键将被以冒号分隔来添加到栏位名称。 所以一个称为 "field[a][b][]" 的栏位将被储存为 "field:a:b:0"。
name字串上传档案的名称。
type字串上传文件的 MIME 类型，由浏览器所定义。
mimetype字串上传档案的 MIME 类型，如同 Upload 类别所确定的。 请注意，这需要安装一个最新的 'mime magic' 档案。 此档案出现在每个 *xin 平台，但在 Windows 平台，你可能必须自己安装这个档案。 如果 MIME 类型不能被确定，此栏位包含的值与 'type' 相同。
file字串上传档案临时位置的完整档案名称。
filename字串上传档案的档案名称（主档名）。
extension字串上传档案的副档名。
size整数上传档案的大小（位元组）。
error布林如果为 true，上传失败的话，错误阵列包含原因。
errors阵列一个阵列群的阵列，每个有两个值。'error'，包含错误代码，以及 'message'，包含错误文字。

请注意，MIME 类型将始终包含最具体的类型。所以如果浏览器宣称它是一个 MS-Word 文件， 但 MIME 类型被测定是 "application/octet-stream"，浏览器的 MIME 类型会被使用，即使这可能是错的或无法预期的！ 例如，一个 Microsoft .xlsx 档案可能被侦测是 "application/zip"。

在你呼叫 save() 方法之后，此阵列结构会被扩充两个额外栏位，给你关于实际储存的资讯。

键类型描述
saved_to字串上传档案被储存的完整路径。
saved_as字串该档案被储存的名称
errors阵列错误阵列（以及错误布林）将在呼叫 save() 来指示任何在试图储存档案时遇到的错误之后被更新。

定义的错误常数

Upload 类别定义以下的错误常数：

名称描述
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 扩充停止了档案上传。PHP 没提供方法来查明是哪个扩充造成档案上传停止；审视 phpinfo() 中的已载入扩充列表可能会有帮助。
UPLOAD_ERR_MAX_SIZE上传档案超过了定义在配置中的最大档案大小。
UPLOAD_ERR_EXT_BLACKLISTED上传档案的副档名被定义在副档名黑名单中。
UPLOAD_ERR_EXT_NOT_WHITELISTED上传档案的副档名没有被定义在副档名白名单中。
UPLOAD_ERR_TYPE_BLACKLISTED上传档案的类型被定义在类型黑名单中。
UPLOAD_ERR_TYPE_NOT_WHITELISTED上传档案的类型没有被定义在类型白名单中。
UPLOAD_ERR_MIME_BLACKLISTED上传档案的 MIME 类型被定义在 MIME 类型黑名单中。
UPLOAD_ERR_MIME_NOT_WHITELISTED上传档案的 MIME 类型没有被定义在 MIME 类型白名单中。
UPLOAD_ERR_MAX_FILENAME_LENGTH上传的档案名称超过了定义的最大档案名称长度。
UPLOAD_ERR_MOVE_FAILED上传的档案名称不能从临时储存移动到指定路径。这可能意味着有一个权限问题。
UPLOAD_ERR_DUPLICATE_FILE上传的档案名称不能被储存因为已存在同名档案。

请注意，为了能够上传档案，你的 HTML <form> 标籤必须包含 enctype="multipart/form-data"， 而且你的表单必须包含至至少一个 "file" 类型的输入栏位。没有它，所有上传将失败，而且 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 方法可被用来检查是否有任何已通过上传验证的上传档案存在。

静态是
参数无
回传布林 - true 如果验证的档案存在，false 如果没有。
範例
// 我们有任何已上传的档案要储存吗？
if (Upload::is_valid())
{
	Upload::save();
}

get_files($index = null)

get_files 方法回传一个所有上传档案中 error 值为 false 的多维阵列。

静态是
参数
参数预设描述
$index选择性档案在已上传档案阵列中的索引数字，或一个表单栏位的名称。如果没指定，会回传一个有所有已验证档案的阵列。 如果该索引数字无效，或如果该索引指向一个有错误状态为 true 的档案，会抛出一个例外。
回传阵列
範例
// 取得成功上传的档案列表
foreach(Upload::get_files() as $file)
{
	// 使用档案资讯做点什幺
}

// 透过索引取得第一个上传的档案
if ( ! Upload::get_files(0))
{
	// 第一个上传的档案没有成功上传
}

get_errors($index = null)

get_errors 方法回传一个所有上传档案中 error 状态为 true 的多维阵列。

静态是
参数
参数预设描述
$index选择性档案在已上传档案阵列中的索引数字，或一个表单栏位的名称。如果没指定，会回传一个有所有已验证档案的阵列。 如果该索引数字无效，或如果该索引指向一个有错误状态为 false 的档案，会抛出一个例外。
回传阵列
範例
// 取得有错误的上传档案列表
foreach(Upload::get_errors() as $file)
{
	// 使用档案资讯做点什幺
}

// 透过栏位名称取得第一个上传的档案
if (Upload::get_errors('new_image'))
{
	// 上传档案的表单栏位 'new_image' 有一个错误
	// 定义为 <input type="file" name="new_image" />
}

请注意，在你表单中的所有上传栏位会被发送，即使它们是选择性的。栏位留空， 上传的档案阵列将有一个空的档案条目，会有一个 Upload::UPLOAD_ERR_NO_FILE 的错误代码。 处理错误时，首先检查错误代码，然后再试着使用任何回传阵列中的其他栏位。

register($event, $callback)

register 方法能让你为特定的上传事件注册回呼（callback）， 并能让你添加你自己的程式码到 process() 和 save() 方法。

静态是
参数
参数预设描述
$event必要你想注册的回呼（callback）事件名称。有效的名称是 'validate'、'before' 和 'after'。
$callback必要有效的 PHP 回呼（callback）函式。这可以是一个函式、一个动态或静态方法、或一个闭包（closure）。
回传布林 - true 如果回呼（callback）被注册，false 如果注册失败。
範例
// 使用闭包（closure）注册 before 回呼（callback）
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' 回呼（callback），确保在你呼叫 Upload::process() 之前注册它。 如果你已经使用 'auto_process' 配置设定，只要你使用 Upload 类别，Upload::process() 将会被呼叫， 这意味着你不能使用此设定，如果你想在执行阶段定义回呼（callback）。

该回呼（callback）将接受一个 FuelPHP\Upload\File 物件做为参数。该条目透过引用传递， 它允许回呼（callback）函式修改阵列中的条目。你可以因为向下相容的原因存取它做为一个阵列， 但如果迁移你的应用程序从版本 < 1.6 到 1.6+，检查传递到你回呼（callback）的值， 因为不是所有属性在 1.6 前都是相同命名。
如果该回呼（callback）函式回传一个整数，它会被假设为一个上传档案错误代码的更新。 所有其他回传值会被忽略。

注意：如果你改变在你的回呼（callback）中的 $file 阵列内容，你必须确保该资讯仍然有效， 因为 Upload 不会再一次执行它的检查。此规则的唯一例外是 'file' 路径， 如果需要它会在回呼（callback）被执行之后被检查并建立。

process($config = array())

process 方法处理关于所有上传档案的资讯， 正规化可被使用表单栏位名称的不同排列组合， 取回额外关于档案及其 MIME 类型的资讯， 并验证档案。

静态是
参数
参数预设描述
$config选择性配置项目的阵列，如此你可以覆写定义在配置档案中的设定。
回传空
抛出FuelException，当没有档案试图上传可被侦测到（即没有 "Enctype" 或 type="file" 输入栏位的表单）
範例
// 处理上传的档案
// 设定最大大小为 10kb，并允许重複档案的覆写
Upload::process(array(
	'max_size'    => 10240,
	'auto_rename' => false,
	'overwrite'   => true
));

如果你打算使用此方法，在配置中停用 auto_process，以避免处理上传的档案两次！

save( ... )

save 方法储存所有已验证的上传档案到指定的路径。

静态是
参数
参数预设描述
$integer选择性透过 get_files() 回传的档案阵列的键。这能让你从一组上传档案中储存一个独立的档案。
$array选择性透过 get_files() 回传的档案阵列的键阵列。这能让你从一组上传档案中储存选择的档案。
$string选择性档案应该被储存的路径。它覆写指定在配置中的路径，或在 process() 方法被呼叫时传递在 $config 阵列中的路径。

请注意，这些参数所给的顺序是不相关的，而他们全都是选择性的。但使用 $integer 或 $array，不要两个都使用。如果你这样做，最后一个指定的会被使用。
回传空
範例
// 储存所有验证的档案
Upload::save();

// 只储存第一个上传的档案
Upload::save(0);

// 储存第一个、第二个和第四个上传的档案
Upload::save(0, 1, 3);

// 储存所有验证的档案，并存到替代的位置
$arr = Upload::get_files();
Upload::save(DOCROOT.'assets', array_keys($arr));

// 处理这些档案的任何错误
foreach (Upload::get_errors() as $key => $file)
{
	// 在这里处理错误
}
免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn