メインコンテンツまでスキップ

画像のアップロード

画像は、ツールバーの画像ボタン、貼り付け(スクリーンショット・コピーしたファイル)、 エディタへのファイルのドロップで追加できます。ファイルはサーバーに送られ、そこで検査・ 保存されたあと、エディタが保存された画像を挿入します。

Laravel の場合​

設定なしで動きます。パッケージがアップロード用のルートを登録し、<x-ohashi-editor> がエディタにそのルートを指定します。

<x-ohashi-editor name="body" :value="old('body', $post->body)" />

必要なもの:

  • PNG・JPEG・WebP に対応した ext-gd。すべての画像を GD で読み込み、書き出し直します。
  • 保存先の公開ディスク。既定は Laravel の public ディスクです。/storage/… の URL が 開けるよう、一度 php artisan storage:link を実行してください。S3 や R2 も使えます (disk を変更)。
  • ログインしているユーザー。ルートには既定で web と auth のミドルウェアが付くので、 セッションと CSRF 対策が効きます。

ルートは POST /ohashi-editor/images、名前は ohashi-editor.images.store です。

サーバーがファイルに対して行うこと​

検査理由
形式はファイルの中身で判定します(PNG・JPEG・GIF・WebP)。ファイル名やブラウザが送った種類は見ません名前を変えただけのファイルを画像として通さないため
SVG は受け付けませんSVG にはスクリプトを含められるため
5 MB・1,600 万画素まで。画素数は画像を展開する前にヘッダーから読みます数 KB のファイルが数十億画素を名乗れるため(圧縮爆弾)
画像を展開して書き出し直します写真の GPS 位置などのメタデータと、ファイルに隠されたもの(画像であると同時に HTML や PHP でもあるファイルなど)が消えます。スマートフォンが EXIF に記録した向きは先に画素へ反映します
中身に合った拡張子のランダムな名前で保存しますパスの細工・上書き・ファイル名からの情報漏れを防ぐため
1 ユーザーあたり 1 分 30 件まで濫用を防ぐため

既知の制限: アニメーション GIF は 1 コマ目だけになります。アニメーション WebP は 受け付けません。展開には幅 × 高さ × 4 バイトほどのメモリが要ります(既定の上限で 64 MB)。memory_limit はそれより大きくしてください。どの記事からも使われなくなった 画像の削除はまだありません(1.x の後の版で予定)。

設定​

設定ファイルを公開し(php artisan vendor:publish --tag=ohashi-editor-config)、 config/ohashi-editor.php の uploads を変更します。

キー既定値意味
enabledtrue(OHASHI_EDITOR_UPLOADS)false にするとルートを登録せず、画像ボタンも出ません
routeohashi-editor/imagesルートの URI
middleware['web', 'auth']アップロードできる人。セッションと CSRF 対策のため web は残してください
rate_limit301 ユーザー(または IP)あたり 1 分の件数。null で無効
diskpublic(OHASHI_EDITOR_DISK)保存先
directoryohashi-editorディスク上のフォルダ
max_kilobytes5120最大のファイルサイズ。PHP の upload_max_filesize と post_max_size もこれを許す必要があります。エディタには小さい方の上限が伝わります
max_pixels16000000最大の画素数
relative_urlstrueアプリ自身が配信する画像は https://ホスト/storage/… ではなく /storage/… で保存します。ドメインを変えても、データベースをステージングに複写しても画像が切れず、APP_URL がブラウザで開いているアドレスと違う場合(php artisan serve でよくある)でも表示されます。別ホスト(S3・CDN)のファイルは常に絶対 URL のままです

エディタごとに、upload-url で送信先を変えたり、:upload-url="false" で アップロードを無効にしたりできます。

<x-ohashi-editor name="comment" :upload-url="false" toolbar="bold italic | link" />

nosniff を付けて配信する​

アップロードしたファイルを配信するのはパッケージではなく Web サーバーやストレージなので、 このヘッダーはそちらで付けてください。nginx の例:

location /storage/ {
add_header X-Content-Type-Options nosniff always;
}

PHP ファイルが実行されるディレクトリを保存先にしないでください。

画像の編集​

画像の設定を開くと、幅(25・50・75・100 %。width 属性として保存)と代替テキストを 設定できます。

  • マウス・タッチ: 画像をクリック(タップ)します。
  • キーボード: 画像の隣にキャレットを置き、Shift+← または Shift+→ で画像を選択して Enter を押します。画像を選択している間は、ツールバーの画像ボタンが「画像を編集」に 変わり、押すと設定が開きます。

開くと代替テキストの欄にフォーカスが移ります。幅のプリセットはその前にあります(Shift+Tab)。 テキストは Enter で適用、Esc で閉じます。どちらでもキャレットは画像の直後に戻ります。 どの変更も「元に戻す」で 1 段ずつ戻せます。

画像を選択せず、キャレットが画像の隣にあるだけのときは、画像ボタンは新しい画像を アップロードします(続けて何枚も入れられるようにするため)。

新しい画像の alt は空です。空の間は、画像の設定に説明を入れるよう促す文が出ます。空のままにするのは飾りだけの画像のときにしてください(エディタはそれを見分けられないので、入力を強制はしません)。

うまくいかなかったとき​

エディタは、ツールバーと本文の間に UI 言語(locale)でメッセージを表示し、 問い合わせ用のエラーコードを添えます。それまでに書いた内容には触れません。

コード状況
OE-UPL-4001ファイルが大きすぎる
OE-UPL-4002PNG・JPEG・GIF・WebP の画像ではない
OE-UPL-4003サーバーに接続できない
OE-UPL-4004ログインが切れた、または CSRF トークンの期限切れ(401・403・419)
OE-UPL-4005サーバー側の失敗(5xx)
OE-UPL-4006画素数が多すぎる
OE-UPL-4007短時間にアップロードしすぎた(429)
OE-UPL-4900その他

失敗するたびに、要素から ohashi-error イベントも発生します。preventDefault() を 呼ぶと、エディタ内のメッセージの代わりに自前の方法で表示できます。

document.addEventListener('ohashi-error', (event) => {
event.preventDefault();
myToast.error(event.detail.message); // detail: { code, message, params, cause }
});

Inertia(Vue 3 / React)​

ルートのパスを渡します。Ziggy では第 3 引数を false にすると、APP_URL から作った絶対 URL ではなく パス(/ohashi-editor/images)になります。APP_URL がブラウザのアドレスと違うと(Laravel の既定の http://localhost と、php artisan serve の 127.0.0.1:8000 など)、絶対 URL は別のオリジンになり、 エディタはログインの Cookie も CSRF トークンも送らないので、アップロードが失敗します。

<OhashiEditor v-model="form.body" name="body" :upload-url="route('ohashi-editor.images.store', undefined, false)" @ohashi-error="onError" />
<OhashiEditor
value={data.body}
onChange={(html) => setData('body', html)}
uploadUrl={route('ohashi-editor.images.store', undefined, false)}
onError={(event) => console.warn(event.detail.code)}
/>

Blade コンポーネントを使わない場合はサイズの上限がエディタに伝わらないので、大きな ファイルはサーバーで初めて拒否されます。送信前に拒否するには、upload-max-size (React では uploadMaxSize)にバイト数を渡してください。

CSRF トークンは自動で取得します。Laravel の XSRF-TOKEN Cookie(Axios が使うもの)と、 ページにあれば <meta name="csrf-token"> です。トークンは同じオリジンにしか送りません。

独自のエンドポイント​

upload-url はどこにでも向けられます。エディタが送るもの:

  • POST・multipart/form-data。ファイルはフィールド image
  • Accept: application/json・X-Requested-With: XMLHttpRequest・Cookie(同じオリジンのみ) と上記の CSRF ヘッダー

期待する応答:

応答意味
201 または 200 { "url": "https://…" }保存済み。url は http(s) か相対 URL
422 { "code": "OE-UPL-4002", "params": {} }拒否。エディタが code に対応するメッセージを表示します
401・403・419、413、429、5xx上のコードに読み替えます

文言ではなくコードを返してください。メッセージはエディタが自分の言語で作ります。

検査と再エンコードはパッケージのフレームワークに依存しない中核にあるので、 素の PHP のエンドポイントからも使えます。

use OhashiEditor\Exception\UploadRejectedException;
use OhashiEditor\Image\ImageProcessor;

try {
$image = (new ImageProcessor())->processFile($_FILES['image']['tmp_name']);
$name = $image->randomFilename(); // 例: 3f9c….png
file_put_contents("/var/www/uploads/{$name}", $image->contents);
http_response_code(201);
echo json_encode(['url' => "/uploads/{$name}"]);
} catch (UploadRejectedException $e) {
http_response_code(422);
echo json_encode(['code' => $e->errorCode()->value, 'params' => $e->params()]);
}

その場合、認証と CSRF 対策はエンドポイント側で行ってください。