README

文件上传包装器是一个PHP库，通过提供一系列易于使用的类来简化文件上传，这些类可以处理常见的验证和处理任务。使用此库，您可以：

轻松验证上传的文件
对特定字段进行针对性的文件处理验证
通过一组易于使用的类简化文件上传过程

入门指南

要使用此库，请按照以下步骤操作

使用Composer安装库

composer require didslm/file-upload-wrapper

导入所需的类

use Didslm\FileUpload\Uploader;
use Didslm\FileUpload\UploaderInterface;
use Didslm\FileUpload\File;
use Didslm\FileUpload\Validation\FileSize;
use Didslm\FileUpload\Validation\FileType;
use Didslm\FileUpload\Validation\Dimension;
use Didslm\FileUpload\FieldValidation;
use Didslm\FileUpload\Attributes\Image;
use Didslm\FileUpload\Attributes\Document;
use Didslm\FileUpload\Exceptions\FileUploadException;

使用upload()方法处理您的实体文件上传

class Product {
    #[Image(requestField: "request_field", dir: "/public")]
    private string $image;
    
    #[Image(requestField: "profile_field", dir: "/public")]
    private string $profile;
    
    // ...
}

$product = new Product();

Uploader::upload($product, [
    new FileType([File::JPEG]),
    new FileSize(2, File::MB)
]);

您还可以通过依赖注入执行相同的示例

class ProductController {
    public function __construct(private UploaderInterface $uploader){}
    
    public function upload(Request $request)
    {
        $product = new Product();
        
        $this->uploader->upload($product, [
            new FileType([File::IMAGES]),
            new FileSize(2, File::MB)
        ]);
    }
}

在本文档的最后，您可以了解如何在Laravel或Symfony中进行配置。

示例

处理实体的文件上传

以下代码展示了如何使用此库处理实体文件上传的示例

class Product {
    //...
    #[Image(requestField: "request_field", dir: "/public")]
    private string $image;
    
    #[Image(requestField: "profile_field", dir: "/public")]
    private string $profile;
    
    public function getImageFilename(): string
    {
        return $this->image;
    }
    
    public function getProfileFilename(): string
    {
        return $this->profile;
    }
}

在此示例中，Product类有两个属性image和profile，它们装饰了Image属性。

类型

以下示例中将展示可用的属性类型列表

#[new Image(requestName: 'file_upload_field', dir: '/upload/dir')]
#[new Document(requestName: 'cv_file', dir: '/upload/dir')]
#[new Video(requestName: 'video_file', dir: '/upload/dir')]

Image属性为库提供元数据，以便在上传期间正确处理文件。

Document属性为库提供元数据，以便在上传期间正确处理文件。

Video属性为库提供元数据，以便在上传期间正确处理文件。

然后，使用Product对象和一组验证规则作为参数调用upload()方法。

$product = new Product();

Uploader::upload($product, [
    new FileType([File::JPEG]),
    new FileSize(2, File::MB)
]);

echo $product->getImageFilename();

处理异常

该库提供了一个FileUploadException类，所有由库抛出的异常都继承自该类。这意味着您可以使用以下方式在try-catch块中捕获所有异常：FileUploadException

try {
    Uploader::upload($product, [
        new FileType([File::PNG]),
        new FileSize(2, File::MB)
    ]);
} catch (FileUploadException $e) {
    // handle exception
}

验证

该库提供了一些验证类，您可以使用这些类来验证上传的文件。这些类可以作为参数传递给upload()方法，以指定正在上传的文件的验证规则。

类型

FileType类用于检查文件类型。您可以通过传递一个文件类型数组给构造函数来指定允许的文件类型。例如

new FileType([File::PNG, File::JPEG, File::GIF])

大小

FileSize类用于验证文件大小。您可以通过传递字节数给构造函数来指定允许的最大文件大小。或者，您可以使用Size类以更易读的格式指定大小。例如

new FileSize(2, File::MB)
new FileSize(200, File::KB)

尺寸

Dimension类用于验证图像的尺寸。您可以通过将最大宽度和高度作为参数传递给构造函数来指定图像的最大宽度和高度。例如

new Dimension(200, 200)

针对性验证

您还可以使用一组验证针对实体中的特定字段。为此，您可以使用FieldValidations类，它接受请求字段名称作为第一个参数，以及一个包含验证规则的数组作为第二个参数。以下是一个示例

$profileValidations = new FieldValidations("profile_field", [
    new Dimension(200, 200),
    new FileSize(2, File::MB)
]);

Uploader::upload($product, [
    new FileType([File::PNG, File::JPEG, File::GIF]),
    $profileValidations,
]);

在上面的例子中，我们指定了一套适用于产品实体配置字段的验证检查。这些检查仅应用于用户上传的配置图像。

框架实现

该库是框架无关的，这意味着您可以使用它与任何框架一起使用。

以下部分展示了如何在一些最流行的框架中配置该库。

Symfony

在您的Symfony应用中，您可以在services.yaml文件中轻松配置该库

services:
    Didslm\FileUpload\:
        resource: '../vendor/didslm/file-upload-wrapper/src/*'

Laravel

在您的Laravel应用中，您可以在AppServiceProvider.php文件中轻松配置该库

public function register()
{
    $this->app->bind(UploaderInterface::class, function (){
         return UploaderFactory::create();
    });
}

处理文件上传可能是一个复杂且容易出错的任务，但使用这个库，您可以简化这个过程，并专注于构建重要的功能。如果您有任何问题或反馈，请随时通过Twitter或LinkedIn联系作者。

didslm / file-upload-wrapper

维护者

详细信息