Ckeditor Widget Laravel Package

Getting Started

Know what you're installing first. friendsofvictoire/ckeditor-widget is a Symfony bundle that ships a CKEditor-backed widget for Victoire DCMS, not a Laravel package. There is no service provider, no facade, no config/ckeditor-widget.php. If you're in a pure Laravel app, the realistic outcome is that you use this repo as a reference implementation for wiring CKEditor into a block-based CMS, not as a dependency. Install it only when you are actually running Victoire (Symfony) alongside or instead of your Laravel app.

Minimal steps in a Victoire/Symfony context:

1. composer require friendsofvictoire/ckeditor-widget
2. Register the bundle in your kernel (AppKernel::registerBundles() on older Symfony, config/bundles.php on Symfony 4+ Flex-style apps).
3. Clear cache (bin/console cache:clear) and confirm the widget appears in the Victoire widget picker in the admin.
4. Drop the widget onto a page, edit, save, and render the page on the front end.

Where to look first:

• The Widget class (typically under Widget/ or Model/) — this is the contract Victoire uses to register the widget and define its editable fields.
• Resources/views/ — the Twig templates for admin editing and front-end rendering. These are the files you'll override 90% of the time.
• Resources/config/ — service definitions and any widget metadata.
• composer.json — check the victoire / Symfony version constraints before assuming compatibility with your stack.

First use case: a rich-text content block on a CMS page — author writes formatted copy in CKEditor, saves, and the front-end template outputs the stored HTML inside your layout.

Implementation Patterns

Widget declaration and rendering. Victoire widgets follow a register-then-render flow: the bundle's widget service is discovered by the Victoire widget registry, and your page template renders it via Victoire's widget rendering helper (typically a Twig function like victoire_widget_render). Treat the widget class as configuration and the Twig template as the thing you actually own.

Template override instead of fork. Copy the bundle's view into app/Resources/.../views/ (or your theme's template dir) under the same path and Symfony's bundle inheritance picks it up. This is the cleanest extension point and keeps you off a fork.

Configuring the editor. CKEditor toolbar/config usually lives either in the widget's form type or in a JS asset the bundle loads. Centralize toolbar profiles in one config location rather than per-widget so editors get a consistent experience across blocks.

Field shape. Keep the persisted field a single text/TEXT column holding HTML. Resist adding structured sub-fields to a rich-text widget; if you need structure, build a separate widget — that's the Victoire pattern and it survives editor changes better.

Bridging into Laravel. If you need CKEditor in Laravel, don't route through this bundle. Use a maintained Laravel CKEditor integration or a plain JS CKEditor 5 build with a Blade component, and store sanitized HTML in a longText column. Use this repo only to study how it defines the editor config and sanitizes on save.

Sanitization on write, not read. Whatever you borrow, sanitize HTML on save (HTMLPurifier-style allowlist) so the front-end template can output raw content safely. Never rely on {!! !!} with unsanitized editor output.

Gotchas and Tips

• Maturity risk is the headline. Zero stars, zero dependents, score 0. Pin an exact version in composer.json, commit composer.lock, and be prepared to vendor-fork if upstream goes quiet. Budget for maintenance you didn't plan.
• Symfony/Victoire version coupling. The bundle's constraints likely target a specific Victoire and Symfony generation (and probably CKEditor 4). Mixing it into a modern Symfony 6/7 app will fight you on autowiring and bundle registration.
• CKEditor 4 vs 5 licensing. CKEditor 4 is end-of-life; CKEditor 5 has its own licensing terms for some plugins. Verify what the bundle actually bundles before shipping to production.
• Assets and cache. After install or template override, run cache:clear and republish assets — stale compiled Twig or missing JS is the most common "widget renders blank" cause.
• Escaping. Front-end templates must output editor HTML raw; that's correct only if you sanitized on save. If the bundle doesn't sanitize, add it in your widget save path.
• Debugging path. Widget not appearing → check bundle registration and the Victoire widget registry. Widget appears but won't save → check the form type and entity mapping. Saves but renders empty → check the template override path and Twig cache.
• Extension points, in order of preference: template override → widget config/parameters → Symfony event subscriber → subclass the widget → fork. Forking is last because it locks you to the upstream's Symfony version.
• Exit strategy. Since this is a tiny, low-traction bundle, isolate its usage behind your own widget/service so swapping to a plain CKEditor integration later is a contained change rather than a page-template rewrite.