VichUploaderBundle 文件上传功能深度解析与实践指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01194/article/details/148942166

VichUploaderBundle 文件上传功能深度解析与实践指南

VichUploaderBundle A simple Symfony bundle to ease file uploads with ORM entities and ODM documents. 项目地址: https://gitcode.com/gh_mirrors/vi/VichUploaderBundle

一、项目概述

VichUploaderBundle 是 Symfony 框架中一个强大的文件上传处理组件，它简化了文件上传、存储和数据库记录的全流程管理。本文将全面解析该组件的核心功能和使用方法，帮助开发者快速掌握文件上传的最佳实践。

二、核心配置详解

2.1 基础配置

在 Symfony 项目中配置上传映射是使用该组件的首要步骤。以下是一个典型的产品图片上传配置示例：

# config/packages/vich_uploader.yaml
vich_uploader:
    db_driver: orm
    metadata:
        type: attribute
    mappings:
        products:
            uri_prefix: /images/products
            upload_destination: '%kernel.project_dir%/public/images/products'
            namer: Vich\UploaderBundle\Naming\SmartUniqueNamer

配置项说明：

uri_prefix: 定义Web访问路径前缀
upload_destination: 设置文件存储的物理路径
namer: 指定文件名生成策略（推荐使用智能唯一命名器）

2.2 高级配置选项

组件提供了丰富的配置选项满足不同场景需求：

vich_uploader:
    mappings:
        products:
            # ...基础配置...
            inject_on_load: false   # 实体加载时是否注入文件对象
            delete_on_update: true  # 更新时是否删除旧文件
            delete_on_remove: true  # 删除实体时是否删除文件

三、实体集成方案

3.1 标准集成模式

以下是产品实体的典型实现方式，包含文件上传所需的所有字段和方法：

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\HttpFoundation\File\File;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

#[ORM\Entity]
#[Vich\Uploadable]
class Product
{
    // ...其他字段...
    
    #[Vich\UploadableField(
        mapping: 'products',
        fileNameProperty: 'imageName',
        size: 'imageSize',
        originalName: 'originalName',
        mimeType: 'mimeType'
    )]
    private ?File $imageFile = null;

    #[ORM\Column(nullable: true)]
    private ?string $imageName = null;

    #[ORM\Column(nullable: true)]
    private ?int $imageSize = null;

    #[ORM\Column(nullable: true)]
    private ?string $originalName = null;

    #[ORM\Column(nullable: true)]
    private ?string $mimeType = null;

    #[ORM\Column(nullable: true)]
    private ?\DateTimeImmutable $updatedAt = null;

    // ...getter和setter方法...
}

关键点说明：

必须使用 #[Vich\Uploadable] 标记实体类
imageFile 属性存储上传的临时文件对象
其他属性记录文件的元信息
更新时间的设置是触发Doctrine事件的关键

3.2 嵌入式对象方案

对于需要更结构化存储的场景，可以使用嵌入式对象：

#[ORM\Entity]
#[Vich\Uploadable]
class Product
{
    // ...其他字段...
    
    #[Vich\UploadableField(
        mapping: 'products',
        fileNameProperty: 'image.name',
        size: 'image.size'
    )]
    private ?File $imageFile = null;

    #[ORM\Embedded(class: 'Vich\UploaderBundle\Entity\File')]
    private ?EmbeddedFile $image = null;
}