Spatie Laravel MediaLibrary 文件上传全指南

Spatie Laravel MediaLibrary 文件上传全指南

laravel-medialibrary Associate files with Eloquent models 项目地址: https://gitcode.com/gh_mirrors/la/laravel-medialibrary

前言

Spatie Laravel MediaLibrary 是一个强大的媒体文件管理工具，它为 Laravel 应用提供了优雅的文件上传、存储和管理解决方案。本文将深入解析该库的文件上传功能，帮助开发者掌握从基础到高级的各种文件添加方式。

核心概念

MediaLibrary 采用链式调用设计，上传流程分为三个部分：

1. 起始方法：选择文件来源（本地路径、URL、请求等）
2. 中间方法（可选）：设置文件名、自定义属性等
3. 结束方法：指定存储位置和集合

这种设计使得代码既简洁又富有表现力。

起始方法详解

1. 从本地文件添加

$model->addMedia($pathToFile)

这是最基本的方法，从服务器本地路径添加文件。注意：默认会移动文件而非复制。

2. 从URL添加

$model->addMediaFromUrl('https://example.com/image.jpg')

适用于从远程获取文件，仅支持 HTTP/HTTPS 协议。

3. 从磁盘添加

$model->addMediaFromDisk('file_key', 's3')

从已配置的文件系统磁盘中获取文件，适合处理云存储中的文件。

4. 从请求添加

// 单个文件
$model->addMediaFromRequest('file_input_name');

// 多个文件
$model->addMultipleMediaFromRequest(['file1', 'file2']);

// 所有文件
$model->addAllMediaFromRequest();

处理表单上传的便捷方法，支持单文件、多文件和批量处理。

5. 特殊数据源

// Base64编码
$model->addMediaFromBase64($base64Data, 'image/png');

// 字符串内容
$model->addMediaFromString('文本内容');

// 数据流
$model->addMediaFromStream($streamResource);

这些方法适合处理非传统文件来源，如API接收的数据或动态生成的内容。

6. 复制文件

$model->copyMedia($pathToFile)

与addMedia不同，此方法会保留原始文件。

中间方法配置

在起始方法和结束方法之间，可以插入各种配置方法：

->preservingOriginal() // 保留原始文件
->usingName('显示名称') // 设置媒体项名称
->usingFileName('存储文件名.ext') // 设置存储时的文件名
->withCustomProperties(['key' => 'value']) // 添加元数据

这些方法可以任意组合，为上传过程添加各种定制选项。

结束方法确定存储

1. 常规存储

->toMediaCollection('collection_name', 'disk_name')

将文件保存到指定集合和磁盘。如果省略参数，则使用默认值。

2. 云存储

->toMediaCollectionOnCloudDisk('collection_name')

使用配置文件中cloud指定的磁盘存储文件，适合云存储优先的场景。

实用技巧

1. 批量处理：当使用addMultipleMediaFromRequest或addAllMediaFromRequest时，返回的是FileAdder集合，需要遍历处理：

$model->addMultipleMediaFromRequest(['photos'])
    ->each(function ($fileAdder) {
        $fileAdder->toMediaCollection('photos');
    });

2. 文件名控制：对于字符串或流生成的文件，默认使用'txt'扩展名，可通过usingFileName自定义：

$model->addMediaFromString('内容')
    ->usingFileName('document.pdf')
    ->toMediaCollection();

3. 元数据管理：利用withCustomProperties存储额外信息，便于后续检索和使用：

$model->addMedia($file)
    ->withCustomProperties([
        'uploader_id' => auth()->id(),
        'original_name' => $file->getClientOriginalName()
    ])
    ->toMediaCollection();

总结

Spatie Laravel MediaLibrary 提供了灵活而强大的文件上传方案，通过理解其链式调用结构和各种方法组合，开发者可以轻松实现从简单到复杂的各种文件管理需求。无论是处理本地文件、远程URL、表单上传还是特殊数据格式，都能找到合适的处理方法。

laravel-medialibrary Associate files with Eloquent models 项目地址: https://gitcode.com/gh_mirrors/la/laravel-medialibrary