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 扩展包，用于优雅地处理文件上传和管理。本文将深入讲解如何检索已上传的媒体文件，这是日常开发中最常用的功能之一。

基础检索方法

获取所有媒体文件

使用 getMedia() 方法可以获取模型关联的所有媒体文件：

$mediaItems = $yourModel->getMedia();

该方法返回一个包含 Media 对象的集合，每个对象代表一个上传的文件。

获取特定集合的媒体文件

如果要获取特定集合中的文件，可以传递集合名称作为参数：

$images = $yourModel->getMedia('images');

获取所有集合中的文件

使用通配符 * 可以获取所有集合中的文件：

$allMedia = $yourModel->getMedia("*");

文件路径与URL获取

基本路径获取

每个 Media 对象都提供了多种获取文件路径和URL的方法：

$publicUrl = $mediaItems[0]->getUrl();         // 相对URL
$publicFullUrl = $mediaItems[0]->getFullUrl(); // 完整URL（包含域名）
$fullPathOnDisk = $mediaItems[0]->getPath();   // 磁盘上的完整路径

S3临时URL

对于存储在S3上的文件，可以生成临时访问URL：

use Carbon\Carbon;

$temporaryS3Url = $mediaItems[0]->getTemporaryUrl(
    Carbon::now()->addMinutes(5)  // 5分钟后过期
);

版本化URL

在配置文件中启用 version_urls 后，URL会包含基于 updated_at 时间戳的版本字符串，非常适合缓存清除场景：

// config/media-library.php
'version_urls' => true,

便捷方法

获取第一个/最后一个媒体文件

这些便捷方法简化了常见场景的代码：

$firstMedia = $yourModel->getFirstMedia();
$firstUrl = $yourModel->getFirstMediaUrl();

$lastMedia = $yourModel->getLastMedia();
$lastUrl = $yourModel->getLastMediaUrl();

媒体文件属性操作

文件名与显示名称

每个 Media 对象都有两个重要的名称属性：

1. name - 显示名称（可自定义）
2. file_name - 实际存储的文件名

// 获取和修改显示名称
echo $mediaItems[0]->name;
$mediaItems[0]->name = '新名称';
$mediaItems[0]->save();

// 获取和修改文件名
$mediaItems[0]->file_name = 'new-file.jpg';
$mediaItems[0]->save();  // 保存时会同时重命名文件系统上的文件

上传时自定义名称

可以在添加文件时就指定这些名称：

$yourModel
   ->addMedia($pathToFile)
   ->usingName('自定义显示名称')
   ->usingFileName('unique-filename.jpg')
   ->toMediaCollection();

文件名清理

对于用户上传的文件名，建议进行清理：

$yourModel
   ->addMedia($pathToFile)
   ->sanitizingFileName(function($fileName) {
      return strtolower(str_replace(['#', '/', '\\', ' '], '-', $fileName));
   })
   ->toMediaCollection();

文件元信息

文件大小

$sizeInBytes = $mediaItems[0]->size;
$humanReadableSize = $mediaItems[0]->human_readable_size; // 如 "1.5 MB"

MIME类型

$mimeType = $mediaItems[0]->mime_type; // 如 "image/jpeg"

删除媒体文件

删除单个文件

$mediaItems[0]->delete(); // 同时删除文件系统中的文件

删除模型时保留媒体文件

默认情况下，删除模型会同时删除关联的媒体文件。如果只想删除模型而保留文件：

$yourModel->deletePreservingMedia();

清空集合

// 清空默认集合
$yourModel->clearMediaCollection();

// 清空特定集合
$yourModel->clearMediaCollection('images');

选择性清空集合

保留集合中的特定文件：

$yourModel->clearMediaCollectionExcept(
    'images', 
    $yourModel->getFirstMedia() // 保留第一个文件
);

最佳实践建议

1. 命名规范：始终对用户上传的文件名进行清理，避免特殊字符导致的问题
2. 版本化URL：生产环境建议启用版本化URL，便于缓存管理
3. 批量操作：处理大量文件时，考虑使用集合方法提高效率
4. 软删除：如果使用软删除，媒体文件不会被自动删除，需要手动处理

通过掌握这些检索和管理方法，你可以高效地利用 Spatie Laravel MediaLibrary 处理项目中的媒体文件需求。

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