blocs/admin: ファイルアップロード機能

管理画面でのファイルアップロード機能の実装方法を説明します。

前提条件: blocs/admin がインストール済みであること

ai-upload クラスの使い方

1. テンプレートで入力フォームを作成

$uploadMessage=lang("template:admin_profile_upload_message")
$uploadDelete=lang("template:admin_profile_upload_delete")

アップロードファイル
ファイル入力: id="file" name="file" class="ai-upload"

2. ルート設定

upload、download、thumbnail のルートが必要です。

Route::middleware(['web', 'auth', Blocs\Middleware\Role::class])
    ->prefix('admin/user')
    ->name('admin.user.')
    ->group(function () {
        Route::post('/upload', [UserController::class, 'upload'])->name('upload');
        Route::get('/{filename}/download', [UserController::class, 'download'])->name('download');
        Route::get('/{filename}/{size}/thumbnail', [UserController::class, 'thumbnail'])->name('thumbnail');
    });

3. アップロードしたファイルを表示

ダウンロードリンクの生成: data-convert="raw_download" サムネイル表示: data-convert="raw_thumbnail"

処理フロー

flowchart TD
    subgraph upload["upload — ファイルのアップロード"]
        direction TB
        u1["validateUpload ★ — アップロードファイルの検証"]
        u2["ファイル保存・レスポンス生成"]
        u1 --> u2
    end

    subgraph download["download — ファイルの表示、ダウンロード"]
        direction TB
        d1["checkDownload ★ — ダウンロード可否の検証"]
        d2["getHeaders ★ — レスポンスヘッダーの設定"]
        d3["ファイル取得・レスポンス返却"]
        d1 --> d2 --> d3
    end

    subgraph thumbnail["thumbnail — サムネイルの表示"]
        direction TB
        t1["checkDownload ★ — ダウンロード可否の検証"]
        t2["getSize ★ — サムネイルサイズの設定"]
        t3["リサイズ・レスポンス返却"]
        t1 --> t2 --> t3
    end

★ はオーバーライドによるカスタマイズポイントです。

FileTrait の詳細

サムネイル生成は Blocs\Thumbnail クラス（admin/src/Thumbnail.php）が担当し、FileTrait の thumbnail メソッドから呼び出されます。

サムネイルの出力品質は app/Consts/Blocs.php の define() で次の定数を設定できます（既定値はいずれも -1＝ライブラリ既定）。

定数	用途
`ADMIN_IMAGE_JPEG_QUALITY`	JPEG 出力品質（`imagejpeg` の第3引数）
`ADMIN_IMAGE_PNG_QUALITY`	PNG 出力品質（`imagepng` の第3引数）

主な変数

変数名	説明
`$this->uploadStorage`	アップロードファイルの保存先パス（デフォルト: `upload`）

オーバーライド可能なメソッド

メソッド名	処理内容
validateUpload($paramname)	アップロードファイルのバリデーション
checkDownload($filename)	ダウンロード可否の検証（権限チェック等）
getHeaders($filename)	ダウンロード時のカスタムレスポンスヘッダーを返す
getSize($size)	サムネイルサイズの定義（`[width, height, crop]` を返す）

サムネイルサイズのプリセット

thumbnail メソッドの $size パラメータに以下の値を指定できます。

サイズ名	説明
s	小サイズ
s@2x	小サイズ（Retina対応）
m	中サイズ
m@2x	中サイズ（Retina対応）
l	大サイズ
l@2x	大サイズ（Retina対応）
thumbnail	デフォルトサムネイル

カスタムサイズが必要な場合は getSize($size) をオーバーライドして [width, height, crop] の配列を返します。

QA

必須にしたい場合

<!-- !file="required" data-lang="ファイルをアップロードしてください。" -->

画像ファイルのみに制限したい場合

<!-- !file="mimes:jpg,jpeg,gif,png" data-lang="画像ファイルを選んでください。" -->

ファイルサイズに上限を設定したい場合

<!-- !file="max:200" data-lang="アップロードファイルが大きすぎます。" -->

複数ファイルをアップロードしたい場合

input に multiple 属性を追加します。

メッセージを変更したい場合

変数	役割
`$uploadMessage`	未アップロード時の案内メッセージ
`$uploadDelete`	削除ボタンに表示するメッセージ

$uploadMessage="画像をドラッグしてドロップしてください。"
$uploadDelete="削除します。"