Ux Editorjs Laravel Package

Getting Started

• This is a Symfony UX bundle, not a Laravel package. You cannot composer require makraz/ux-editorjs in a Laravel app and expect the form type, EasyAdmin field, or upload controller to work. Start by treating it as a reference implementation: inspect the Stimulus controller (JS), the tool DTOs under src/Tool/, and the upload handler interface.
• First practical use case: add Editor.js to a Blade form. Install @editorjs/editorjs plus the tool packages you need via npm. Copy/adapt the bundle’s Stimulus controller into a plain JS module (or use it with Laravel’s Stimulus integration if you have one). Initialize Editor.js against a div, sync editor.save() JSON into a hidden input on form submit.
• Where to look first: the EditorjsType shows how form options map to Editor.js config (placeholder, minHeight, readOnly, etc.). The UploadHandlerInterface and built-in upload controller are good blueprints for a Laravel upload endpoint. The CustomTool DTO shows the pattern for registering arbitrary tools without writing JS glue.

Implementation Patterns

• Blade component wrapper: create <x-editorjs name="content" :options="[...]" /> that renders a container and hidden input. Use @push('scripts') to initialize Editor.js with options from props. Listen to the editor’s change event (or the bundle’s editorjs:change concept) to update the hidden input before submit.
• Tool configuration via PHP arrays/DTOs: borrow the DTO pattern. Keep a config/editorjs.php map of tool name → npm class + config. Example: 'header' => ['class' => 'Header', 'config' => ['levels' => [1,2,3]]]. This mirrors the bundle’s enums/DTOs without pulling in Symfony form dependencies.
• Image uploads: implement a Laravel controller that mimics UploadHandlerInterface. Accept the file, validate MIME/size with Laravel rules, store via Storage::disk('public') or s3, and return { success: 1, file: { url: ... } }. Use the bundle’s local/Flysystem logic as a guide; Laravel’s filesystem abstraction covers S3/GCS/Azure/SFTP natively.
• Livewire/Inertia: the bundle supports Symfony Live Components via data-live-ignore. In Livewire, add wire:ignore to the editor container. In Inertia, initialize in onMounted and destroy in onUnmounted to avoid duplicate instances.
• Custom tools and tunes: use CustomTool and TuneInterface as templates. On the Laravel side, register the tool’s JS class in the editor config and keep a small PHP DTO/array for server-side rendering options if you need to pre-populate or transform blocks. Pass block tunes globally in the tunes array.

Gotchas and Tips

• Symfony coupling: the form type, EasyAdmin field, and upload controller are Symfony-specific. Do not expect them to work in Laravel without rewriting. The JS controller and DTO patterns are portable; the PHP form integration is not.
• Stimulus bundle requirement: the bundle requires symfony/stimulus-bundle. Laravel does not use it by default. If you copy the controller, remove Symfony-specific imports and dispatch your own events or use Laravel’s event system.
• Experimental BC breaks: v0.1.0 explicitly says backwards compatibility is not guaranteed. Pin the version if you copy code, and vendor the JS controller rather than relying on future updates. DTO class names and config keys may change.
• Image upload security: the built-in upload controller validates max size and MIME types, but always re-validate in Laravel. Never trust client-side allowedFileTypes. Use mimes/max rules, sanitize filenames, and consider storing outside the public root if serving through a controller.
• Multiple editors: the bundle supports multiple instances. In Laravel, ensure each editor has a unique DOM ID and hidden input name. Generate IDs with uniqid() or Str::uuid() in the Blade component.
• Debugging: use the bundle’s editorjs:options, editorjs:connect, and editorjs:change events as inspiration for your own hooks. Log the JSON output before saving to catch malformed blocks. In Laravel, you can also validate the JSON structure server-side before persisting.
• Extension points: copy the AbstractTool and CustomTool DTO patterns, not the Symfony-coupled code. If you need to render saved Editor.js blocks in Blade, write a renderer that maps block types to views/partials and sanitizes raw HTML blocks.