README

框架无关的上传处理库。

特性

1. 对文件进行验证，遵循常规规则：扩展名、文件大小、图片大小（宽度、高度、比例）。为此，它使用Sirius Validation。
2. 将有效的上传文件移动到容器中。容器通常是本地文件夹，但您可以实现自己的或使用其他文件系统抽象，如Gaufrette或Flysystem。

简要介绍

use Sirius\Upload\Handler as UploadHandler;
$uploadHandler = new UploadHandler('/path/to/local_folder');

// optional configuration
$uploadHandler->setOverwrite(false); // do not overwrite existing files (default behaviour)
$uploadHandler->setPrefix('subdirectory/append_'); // string to be appended to the file name
$uploadHandler->setAutoconfirm(false); // disable automatic confirmation (default behaviour)

// validation rules
$uploadHandler->addRule('extension', ['allowed' => 'jpg', 'jpeg', 'png'], '{label} should be a valid image (jpg, jpeg, png)', 'Profile picture');
$uploadHandler->addRule('filesize', ['max' => '20M'], '{label} should have less than {max}', 'Profile picture');
$uploadHandler->addRule('imageratio', ['ratio' => 1], '{label} should be a sqare image', 'Profile picture');

$result = $uploadHandler->process($_FILES['picture']); // ex: subdirectory/my_headshot.png

if ($result->isValid()) {
	// do something with the image like attaching it to a model etc
	try {
		$profile->picture = $result->name;
		$profile->save();
		$result->confirm(); // this will remove the uploaded file and it's .lock file
	} catch (\Exception $e) {
		// something wrong happened, we don't need the uploaded picture anymore
		$result->clear();
		throw $e;
	}
} else {
	// image was not moved to the container, where are error messages
	$messages = $result->getMessages();
}

一个聚合器统治一切

有时您的表单可能向服务器上传多个文件。为了减少process()、clear()和confirm()调用次数，您可以使用“上传处理聚合器”

use Sirius\Upload\HandlerAggregate as UploadHandlerAggregate;
$uploadHandlerAggregate = new UploadHandlerAggregate();
$uploadHandlerAggregate->addHandler('picture', $previouslyCreatedUploadHandlerForTheProfilePicture);
$uploadHandlerAggregate->addHandler('resume', $previouslyCreatedUploadHandlerForTheResume);

$result = $uploadHandlerAggregate->process($_FILES);

if ($result->isValid()) {
	// do something with the image like attaching it to a model etc
	try {
		$profile->picture = $result['picture']->name;
		$profile->resume = $result['resume']->name;
		$profile->save();
		$result->confirm(); // this will remove the uploaded file and it's .lock file
	} catch (\Exception $e) {
		// something wrong happened, we don't need the uploaded files anymore
		$result->clear();
		throw $e;
	}
} else {
	// image was not moved to the container, where are error messages
	$messages = $result->getMessages();
}

您可以在tests/web/index.php中看到聚合器和处理器的实际应用

工作原理

1. 上传的文件会根据规则进行验证。默认情况下，库将检查上传是否有效（即：上传过程中没有错误）
2. 上传文件的名称会被净化（只保留字母、数字和下划线，并将结果转换为小写）。如果您想，可以实施自己的净化函数。
3. 如果不允许覆盖，并且容器中已存在同名文件，库将给文件名前缀添加时间戳。
4. 将上传的文件移动到容器中。它还会创建一个锁文件（文件名 + '.lock'），以便我们知道上传尚未确认
5. 如果您的应用程序中发生错误并且您想删除上传的文件，您可以通过clear()上传的文件来删除文件及其.lock文件。只有附加了对应.lock文件的文件才能被清除
6. 如果一切正常，您可以通过confirm上传。这将删除附加到上传文件的.lock文件。

什么是“锁定”？

通常，应用程序接受文件上传以存储它们以供将来使用（产品图片、个人简历等）。但是，从上传文件移动到其实际数据存储的容器中，可能会发生一些错误（例如，数据库宕机）。因此，实施了锁定功能。这样，即使您无法执行clear()方法，您也能查看容器并找到未使用的文件。必须谨慎使用此功能

1. 如果您想利用此功能，必须使用confirm
2. 如果您不喜欢它，使用$uploadHandler->setAutoconfirm(true)，所有上传的文件将自动确认

使用不同的容器

如果您想将上传的文件存储在不同的位置，您的容器必须实现Sirius\Upload\Container\ContainerInterface。

$amazonBucket = new AmazonBucket();
$container = new AmazonContainer($amazonBucket);
$uploadHandler = new UploadHandler($container);

您可以在Gaufrette或Flysystem之上轻松创建上传容器。

重要提示

1. 该库不假设上传文件的“网络可用性”。

大多数时候，一旦您有了有效的上传，新文件将在互联网上可访问。您可以将文件上传到/var/www/public/images/users/，并通过//cdn.domain.com/users/访问文件。让您的应用程序使用上传的结果取决于您。

2. 如果多个上传文件具有相同的名称，您可以同时处理它们

如果您上传多个同名文件（例如：<input type="file" name="pictures[]">），但请注意，process() 和 getMessages() 方法将返回数组

$result = $uploadHandler->process($_FILES['pictures']);
// will return a collection of files which implements \Iterator interface
$messages = $result->getMessages();
// may return if the second file is not valid
array(
	'1' => 'File type not accepted'
);

在这种情况下，库将正常化 $_FILES 数组，因为 PHP 会搞乱上传数组。当某些文件上传失败时（例如：保留有效文件继续上传或显示无效图片的错误信息），您需要决定如何处理