medialibrary-development

メディアライブラリの開発

概要

spatie/laravel-medialibrary を使用して、ファイルを Eloquent モデルに関連付けます。画像・動画の変換、レスポンシブ画像、複数のコレクション、さまざまなストレージディスクに対応しています。

有効化するタイミング

• Laravel でファイルのアップロード、メディアの添付、画像処理を行う場合に有効化します。
• コードで HasMedia、InteractsWithMedia、Media モデル、またはメディアコレクションや変換を参照している場合に有効化します。
• Eloquent モデルに添付されたファイルの追加、取得、変換、管理をユーザーが希望している場合に有効化します。

対象範囲

• 対象：メディアのアップロード、コレクション、変換、レスポンシブ画像、カスタムプロパティ、ファイルの取得、パスや URL の生成。
• 対象外：Eloquent との関連付けを伴わない一般的なファイルストレージ、Laravel 以外のフレームワーク。

ワークフロー

1. タスクを特定します（モデルのセットアップ、メディアの追加、変換の定義、ファイルの取得など）。
2. references/medialibrary-guide.md を読み、関連するセクションを確認します。
3. リファレンスのパターンを適用し、コードを最小限に保ち、Laravel 標準の書き方にします。

主な概念

モデルのセットアップ

メディアを扱うすべてのモデルは、HasMedia を実装し、InteractsWithMedia トレイトを使用する必要があります。

use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class BlogPost extends Model implements HasMedia
{
    use InteractsWithMedia;
}

メディアの追加

$blogPost->addMedia($file)->toMediaCollection('images');
$blogPost->addMediaFromUrl($url)->toMediaCollection('images');
$blogPost->addMediaFromRequest('file')->toMediaCollection('images');

コレクションの定義

public function registerMediaCollections(): void
{
    $this->addMediaCollection('avatar')->singleFile();
    $this->addMediaCollection('downloads')->useDisk('s3');
}

変換の定義

use Spatie\MediaLibrary\MediaCollections\Models\Media;
use Spatie\Image\Enums\Fit;

public function registerMediaConversions(?Media $media = null): void
{
    $this->addMediaConversion('thumb')
        ->fit(Fit::Contain, 300, 300)
        ->nonQueued();
}

メディアの取得

$url = $model->getFirstMediaUrl('images');
$thumbUrl = $model->getFirstMediaUrl('images', 'thumb');
$allMedia = $model->getMedia('images');

推奨事項と禁止事項

推奨事項：

• InteractsWithMedia トレイトと併せて、必ず HasMedia インターフェースを実装します。
• registerMediaConversions() のパラメーターには ?Media $media = null を使用します。
• メディアの追加を確定するには ->toMediaCollection() を呼び出します。
• 同期的に実行する変換には ->nonQueued() を使用します。
• ファイルを 1 つだけ保持するコレクションには ->singleFile() を使用します。
• fit メソッドには Spatie\Image\Enums\Fit の列挙値を使用します。

禁止事項：

• マイグレーションの実行前に、必ず php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations" を実行してください。
• ディスクの設定に env() を使用しないでください。config() を使用するか、config/media-library.php で設定してください。
• toMediaCollection() を呼び出さずに addMedia() を呼び出さないでください。メディアが保存されません。
• registerMediaConversions() に登録されていない変換名を参照しないでください。

リファレンス

• references/medialibrary-guide.md