Skip to main content

Image uploads

Images can be added with the toolbar's image button, by pasting (a screenshot, a copied file) or by dropping files onto the editor. Each file is sent to your server, checked and stored there; the editor then inserts the stored image.

With Laravel​

It works out of the box. The package registers an upload route, and <x-ohashi-editor> points the editor at it:

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

What you need:

  • ext-gd with PNG, JPEG and WebP support. Every image is decoded and written out again with GD.
  • A public disk to store to. The default is Laravel's public disk; run php artisan storage:link once so /storage/… URLs work. S3 or R2 work too (set disk).
  • A logged-in user. The route uses the web and auth middleware by default, so it has a session and CSRF protection.

The route is POST /ohashi-editor/images, named ohashi-editor.images.store.

What the server does with a file​

CheckWhy
The format is read from the bytes: PNG, JPEG, GIF or WebP. The file name and the type the browser sent are ignoredA renamed file cannot pass as an image
SVG is never acceptedSVG can carry script
At most 5 MB and 16 megapixels. The pixel count is read from the header before the image is decodedA few kilobytes can claim to be gigapixels (decompression bomb)
The image is decoded and re-encodedMetadata such as the GPS position in photos is removed, and so is anything hidden in the file (a file that is both an image and HTML or PHP comes out as only an image). The rotation phones record in EXIF is applied first
Stored under a random name with the extension that matches the contentNo path tricks, no overwriting, no leaked file names
At most 30 uploads per minute per userAbuse

Known limits: animated GIFs keep only their first frame; animated WebP is not accepted. Decoding needs about width × height × 4 bytes of memory — 64 MB at the default limit — so keep memory_limit above that. Images that are no longer used by any post are not removed yet (planned for a later 1.x release).

Configuration​

Publish the config (php artisan vendor:publish --tag=ohashi-editor-config) and change uploads in config/ohashi-editor.php:

KeyDefaultMeaning
enabledtrue (OHASHI_EDITOR_UPLOADS)false registers no route; the image button disappears
routeohashi-editor/imagesThe route's URI
middleware['web', 'auth']Who may upload. Keep web for the session and CSRF protection
rate_limit30Uploads per minute per user (or IP). null turns it off
diskpublic (OHASHI_EDITOR_DISK)Where files go
directoryohashi-editorFolder on the disk
max_kilobytes5120Largest file. PHP's upload_max_filesize and post_max_size must allow it too; the editor is told the lower of the limits
max_pixels16000000Largest image, in pixels
relative_urlstrueImages served by the app itself are saved as /storage/…, not https://your-host/storage/…: posts survive a domain change and a copy of the database on staging, and images show even when APP_URL is not the address in the browser (common with php artisan serve). Files on another host (S3, a CDN) always keep their absolute URL

For one editor, upload-url overrides the endpoint and :upload-url="false" turns uploads off:

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

Serve uploads with nosniff​

Uploaded files are served by your web server or storage, not by the package, so set this header there. For nginx:

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

Never point the disk at a directory where PHP files are executed.

Editing an image​

Open an image's settings to set its width (25, 50, 75 or 100 %, stored as the width attribute) and its alternative text:

  • Pointer: click (tap) the image.
  • Keyboard: put the caret next to the image and select it with Shift+← or Shift+→, then press Enter. While an image is selected, the toolbar's image button reads "Edit image" and opens the settings too.

Focus goes to the alternative text. The width presets come before it (Shift+Tab). Press Enter to apply the text, Esc to close; either way the caret returns right after the image. Each change is one step in Undo.

With the caret merely next to an image (nothing selected), the image button uploads a new image, so several images can be added in a row.

New images get an empty alt. While it is empty, the settings show a reminder to describe the image; leave it empty only for purely decorative images (the editor cannot tell those apart, so it never insists).

When something goes wrong​

The editor shows a message between the toolbar and the text, in its UI language (locale), with an error code for support. The text written so far is never touched.

CodeWhen
OE-UPL-4001The file is too large
OE-UPL-4002Not a PNG, JPEG, GIF or WebP image
OE-UPL-4003No connection to the server
OE-UPL-4004Not logged in any more, or the CSRF token expired (401, 403, 419)
OE-UPL-4005The server failed (5xx)
OE-UPL-4006The image has too many pixels
OE-UPL-4007Too many uploads in a short time (429)
OE-UPL-4900Anything else

Every failure also fires an ohashi-error event on the element. Call preventDefault() to show it your own way instead:

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

Inertia (Vue 3 / React)​

Pass the route's path. With Ziggy, the third argument false gives a path (/ohashi-editor/images) rather than an absolute URL built from APP_URL: when APP_URL is not the address in the browser (Laravel's default http://localhost against php artisan serve on 127.0.0.1:8000), an absolute URL is another origin, and the editor sends it neither the session cookie nor the CSRF token, so uploads fail.

<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)}
/>

Without the Blade component nobody tells the editor the size limit, so large files are only refused by the server. Pass upload-max-size (uploadMaxSize in React), in bytes, to refuse them before they are sent.

The CSRF token is picked up automatically: Laravel's XSRF-TOKEN cookie (the one Axios uses) and <meta name="csrf-token"> if the page has it. Tokens are only sent to your own origin.

Your own endpoint​

upload-url can point anywhere. The editor sends:

  • POST, multipart/form-data, the file in the field image
  • Accept: application/json, X-Requested-With: XMLHttpRequest, cookies (same origin only) and the CSRF headers above

and expects:

ResponseMeaning
201 or 200 { "url": "https://…" }Stored. url must be http(s) or relative
422 { "code": "OE-UPL-4002", "params": {} }Refused; the editor shows the message for code
401 / 403 / 419, 413, 429, 5xxMapped to the codes above

Send codes, not text: the editor writes the message in its own language.

The checks and re-encoding are in the package's framework-independent core, so a plain PHP endpoint can use them too:

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

try {
$image = (new ImageProcessor())->processFile($_FILES['image']['tmp_name']);
$name = $image->randomFilename(); // e.g. 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()]);
}

Authentication and CSRF protection are then up to your endpoint.