Ckeditor Widget Laravel Package

Getting Started

• Install alongside the Victoire CMS (required — this package is a Victoire widget, not a standalone CKEditor bundle):

  composer require victoire/ckeditor-widget
  

• First stop is the Widget/ directory of the package: it contains the widget class (typically CKEditorWidget extends AbstractWidget), its form type (e.g. CKEditorWidgetType), and the matching Twig template under Resources/views/. Read those three files before anything else — the entire package is essentially those files plus config.
• Register the widget with Victoire's widget manager (tag it, or rely on the package's Resources/config/services.yml autoloading if present), then clear the cache so the page-builder palette picks it up:

  php bin/console cache:clear
  

• First use case: open a Victoire page in the page builder, drag the "CKEditor" (rich text) widget into a slot, type into the WYSIWYG, save, and confirm it renders on the front end. That single flow exercises the widget class, form type, render template and business-entity persistence all at once — if it works end to end, the install is correct.
• Confirm the exact class/namespace names in the package's source before wiring anything; this repo predates consistent Victoire conventions and naming changed across Victoire versions.

Implementation Patterns

• Widget class pattern. The package follows Victoire's AbstractWidget convention. The widget class declares getName(), often getWidgetMap(), and any extra data fields via a form type. To customise behaviour (default toolbar, extra button sets, placeholder text), subclass the widget and register your subclass instead of editing vendor code.
• Form-type coupling. The widget's data is edited via a Symfony form type. If you need extra options (toolbar profile, allowed tags, a caption field), you add them to the form type — but you almost always do this by extending the existing type in your app's Form/ directory and overriding the template, not by patching the vendor package.
• Template override. Victoire resolves widget templates by convention (Resources/views/Widget/<widgetName>.html.twig). Drop a template of the same name in your app's templates/ (or app/Resources/ on older Symfony) to override the CKEditor widget's rendering without touching vendor. This is the primary integration point.
• Business-entity persistence. Victoire widgets render from a business entity (Widget/BusinessEntity rows) with widget data stored as serialized/JSON fields. When debugging "my text saved but doesn't show", inspect the business entity's stored data before blaming the template — mismatches between form field names and template variable names are the most common failure.
• Integration inside a Victoire slot layout. Use the widget inside Victoire's page/slot layout system rather than embedding it manually. The widget assumes it is being rendered by Victoire's renderer and relies on that context (widget id, slot, rendering context) being present.
• Config-driven CKEditor. CKEditor configuration lives in the widget template/JS (usually a CKEDITOR.replace(...) call or a config object passed to the widget). Centralise toolbar config in your app's CKEditor config file and reference it from your overridden template so multiple widgets share one profile rather than duplicating config inline.
• Custom widget variants. For repeated use cases (intro text, legal footer), create a thin subclass with a fixed name and preconfigured toolbar, register it as its own widget, and let editors pick it from the palette. This is cheaper than a settings UI for every text block.

Gotchas and Tips

• This package is effectively abandoned. Last release was 2017, it has almost no stars and no dependents. Do not start a new project on it, and if you inherit it, plan a migration path. Pin your Victoire/Symfony versions and treat the package as frozen.
• CKEditor 4, not 5. The bundled editor is CKEditor 4-era. It reached end-of-life in 2023 and has known security vulnerabilities. Audit and plan a replacement (or at minimum, restrict who can edit content) before exposing it publicly.
• Symfony version lock. It expects the Symfony/Victoire generation from that era (Symfony 2.8/3.x). On modern Symfony the widget registration and template resolution will not work without shimming. Check composer.json requirements before assuming compatibility.
• Widget registration is silent when wrong. If the widget doesn't appear in the page-builder palette, the service tag or widget-map entry is missing or misspelled. Debug by dumping the widget manager's registered widgets (bin/console debug:container for the widget registry service) rather than guessing.
• Cache is aggressive. Victoire caches widget lists and templates. Almost every "my change didn't apply" issue is a stale cache — cache:clear (and on some setups manually clearing var/cache) before investigating further.
• Template name collisions. Widget templates are resolved by convention; an overriding template with the wrong filename silently does nothing, and you'll spend time editing the vendor file that isn't being used. Confirm which template is actually rendered via Twig's debug output ({{ dump() }} with the debug bundle) or the Symfony profiler's template panel.
• Content stored as HTML is unescaped by design. Rendered widget output is raw HTML from CKEditor, so XSS is only as controlled as your editor permissions and allowed-tag configuration. Don't grant the widget to untrusted roles, and configure allowedContent/disallowedContent carefully.
• Extension points are limited to three: subclass the widget, override the Twig template, extend the form type. There is no plugin API and no config tree worth documenting — that's the whole surface area. Plan customisation accordingly.