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-gdwith 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
publicdisk; runphp artisan storage:linkonce so/storage/…URLs work. S3 or R2 work too (setdisk). - A logged-in user. The route uses the
webandauthmiddleware 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
| Check | Why |
|---|---|
| The format is read from the bytes: PNG, JPEG, GIF or WebP. The file name and the type the browser sent are ignored | A renamed file cannot pass as an image |
| SVG is never accepted | SVG can carry script |
| At most 5 MB and 16 megapixels. The pixel count is read from the header before the image is decoded | A few kilobytes can claim to be gigapixels (decompression bomb) |
| The image is decoded and re-encoded | Metadata 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 content | No path tricks, no overwriting, no leaked file names |
| At most 30 uploads per minute per user | Abuse |
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:
| Key | Default | Meaning |
|---|---|---|
enabled | true (OHASHI_EDITOR_UPLOADS) | false registers no route; the image button disappears |
route | ohashi-editor/images | The route's URI |
middleware | ['web', 'auth'] | Who may upload. Keep web for the session and CSRF protection |
rate_limit | 30 | Uploads per minute per user (or IP). null turns it off |
disk | public (OHASHI_EDITOR_DISK) | Where files go |
directory | ohashi-editor | Folder on the disk |
max_kilobytes | 5120 | Largest file. PHP's upload_max_filesize and post_max_size must allow it too; the editor is told the lower of the limits |
max_pixels | 16000000 | Largest image, in pixels |
relative_urls | true | Images 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.
| Code | When |
|---|---|
OE-UPL-4001 | The file is too large |
OE-UPL-4002 | Not a PNG, JPEG, GIF or WebP image |
OE-UPL-4003 | No connection to the server |
OE-UPL-4004 | Not logged in any more, or the CSRF token expired (401, 403, 419) |
OE-UPL-4005 | The server failed (5xx) |
OE-UPL-4006 | The image has too many pixels |
OE-UPL-4007 | Too many uploads in a short time (429) |
OE-UPL-4900 | Anything 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 fieldimageAccept: application/json,X-Requested-With: XMLHttpRequest, cookies (same origin only) and the CSRF headers above
and expects:
| Response | Meaning |
|---|---|
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, 5xx | Mapped 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.