画像のアップロード
画像は、ツールバーの画像ボタン、貼り付け(スクリーンショット・コピーしたファイル)、 エディタへのファイルのドロップで追加できます。ファイルはサーバーに送られ、そこで検査・ 保存されたあと、エディタが保存された画像を挿入します。
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 を変更します。
| キー | 既定値 | 意味 |
|---|---|---|
enabled | true(OHASHI_EDITOR_UPLOADS) | false にするとルートを登録せず、画像ボタンも出ません |
route | ohashi-editor/images | ルートの URI |
middleware | ['web', 'auth'] | アップロードできる人。セッションと CSRF 対策のため web は残してください |
rate_limit | 30 | 1 ユーザー(または IP)あたり 1 分の件数。null で無効 |
disk | public(OHASHI_EDITOR_DISK) | 保存先 |
directory | ohashi-editor | ディスク上のフォルダ |
max_kilobytes | 5120 | 最大のファイルサイズ。PHP の upload_max_filesize と post_max_size もこれを許す必要があります。エディタには小さい方の上限が伝わります |
max_pixels | 16000000 | 最大の画素数 |
relative_urls | true | アプリ自身が配信する画像は 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-4002 | PNG・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。ファイルはフィールドimageAccept: 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 対策はエンドポイント側で行ってください。