Download the PHP package mati365/ckeditor5-symfony without Composer

ckeditor5-symfony

CKEditor 5 for Symfony >=6.4.x — a lightweight WYSIWYG editor integration for Symfony. Easy to set up, it supports custom builds, dynamic loading, and localization. The package includes JavaScript and CSS assets, making it simple to integrate CKEditor 5 into your Symfony applications.

[!IMPORTANT] This integration is unofficial and not maintained by CKSource. For official CKEditor 5 documentation, visit ckeditor.com. If you encounter any issues in editor, please report them on the GitHub repository.

Table of Contents

• ckeditor5-symfony
  • Table of Contents
  • Compatibility 🔗
  • Installation 🚀
  • Usage 📖
  • Editor Types 🖊️
  • Classic editor 📝
  • Multiroot editor 🌳
  • Inline editor 📝
  • Balloon editor 🎈
  • Decoupled editor 🌐
  • Configuration ⚙️
  • Custom Presets 🧩
  • Override configuration 🎯
  • Dynamic Presets 🎨
  • Providing the License Key 🗝️
  • Referencing DOM Elements in Config 🏷️
  • Localization 🌍
  • CDN Translation Loading 🌐
    • AssetsMapper local translations assignment 📦
    • Global CDN translation loading ☁️
  • Global Translation Config 🛠️
    • AssetsMapper translations installation 📥
    • Direct CDN translations configuration ⚙️
  • Custom translations 🌐
    • Translation references in config 🔤
  • Paragraph-like editing 📄
  • Classic / Balloon / Inline editor
  • Decoupled editor
  • Multiroot editor
  • Forms Integration 🧾
  • Editor roots change event 📡
  • Custom plugins 🧩
  • Context 🤝
  • Basic usage 🔧
  • Custom context translations 🌐
  • Editors and Contexts registry 👀
  • Installer command options ⚙️
  • Development ⚙️
  • Running Tests 🧪
  • Psst... 👀
  • Trademarks 📜
  • License 📜

Compatibility 🔗

Installation 🚀

1. Install the package:

2. Enable the bundle:

3. Run the installer:

   Choose the distribution method that best fits your needs:

   🏠 Self-hosted via AssetsMapper (Recommended) Bundles assets locally. No Node.js required.

   📦 Self-hosted via Webpack Encore Requires Node.js and a bundler like Webpack Encore. Assets are bundled with your application.

   and then add the following line to your main JavaScript file (e.g., assets/app.js):

   📡 CDN Distribution Loads assets from CKSource CDN.

   _For CDN, add CKEDITOR5_LICENSE_KEY="your-key" to your .env file._

   💡 Tip: Add --premium to either command to install premium features (requires a valid license).

   For more options, see Installer command options.

Usage 📖

To use CKEditor 5 in your Twig templates, simply call the cke5_editor() function:

If you don't use AssetsMapper, and your distribution is set to cloud, make sure to include the assets using cke5_cloud_assets() in your <head> section.

Editor Types 🖊️

CKEditor 5 Symfony supports four distinct editor types, each designed for specific use cases. Choose the one that best fits your application's layout and functionality requirements.

Classic editor 📝

Traditional WYSIWYG editor with a fixed toolbar above the editing area. Best for standard content editing scenarios like blog posts, articles, or forms.

Multiroot editor 🌳

Advanced editor supporting multiple independent editable areas within a single editor instance. Perfect for complex layouts like page builders, newsletters, or multi-section content management.

Inline editor 📝

Minimalist editor that appears directly within content when clicked. Ideal for in-place editing scenarios where the editing interface should be invisible until needed.

Note: Inline editors don't work with <textarea> elements and may not be suitable for traditional form scenarios.

Balloon editor 🎈

Contextual editor that shows a floating toolbar when text is selected. Great for simple editing tasks where a full toolbar isn't necessary.

Decoupled editor 🌐

Flexible editor where toolbar and editing area are completely separated. Provides maximum layout control for custom interfaces and complex applications.

Configuration ⚙️

You can configure the editor presets in your config/packages/ckeditor5.yaml file. The default preset is default, which provides a basic configuration with a toolbar and essential plugins. The preset is a map that contains the editor configuration, including the toolbar items and plugins. There can be multiple presets, and you can switch between them by passing the preset keyword argument to the cke5_editor function.

Custom Presets 🧩

In order to override the default preset or add custom presets, you can add the following configuration:

In template:

The default one is specified here src/DependencyInjection/DefaultConfiguration.php.

Override configuration 🎯

You can also override configuration at runtime by passing config or mergeConfig arguments to the editor function. This is useful if you want to change the editor configuration based on user input or other conditions.

Dynamic Presets 🎨

For more complex scenarios, you can create preset configurations programmatically in your controller using PresetParser::parse(). This is useful when you need to build editor configurations based on user permissions, database settings, or other runtime conditions.

Then in your template, pass the preset object directly:

This approach gives you full control over editor configuration at runtime, allowing you to customize it based on application logic, user roles, or any other dynamic conditions.

Providing the License Key 🗝️

CKEditor 5 requires a license key when using the official CDN or premium features. You can provide the license key in two simple ways:

1. Environment variable: Set the CKEDITOR5_LICENSE_KEY environment variable in your .env file. This is the easiest and most common way.
2. Preset config: You can also set the license key directly in your preset configuration in config/packages/ckeditor5.yaml:

If you use CKEditor 5 under the GPL license, you do not need to provide a license key. However, if you choose to set one, it must be set to GPL.

If both are set, the preset config takes priority. For more details, see the CKEditor 5 licensing guide.

Referencing DOM Elements in Config 🏷️

You can reference DOM elements directly in your editor configuration using the special { $element: "selector" } format. This is useful when you want to attach the editor's UI parts (like toolbars or editable areas) to specific elements in your HTML.

This will find the elements with IDs my-toolbar and my-editable in the DOM and use them for the editor's UI.

⚠️ If the element is not found, a warning will be shown in the console.

Localization 🌍

Support multiple languages in the editor UI and content. Learn how to load translations via CDN or configure them globally.

CDN Translation Loading 🌐

Depending on your setup, you can preload translations via CDN.

AssetsMapper local translations assignment 📦

If you want to load a specific language for the editor UI, you can specify the language argument in the cke5_editor() function:

Remember, that this only works if you have installed the translations using the ckeditor5:assets-mapper:install command with the --translations option.

Global CDN translation loading ☁️

If you don't use AssetsMapper, you can load translations directly from CDN by specifying them in the preset config or during installation. See Global Translation Config for more details.

If you want to specify it in the template,you can use cke5_cloud_assets() function:

Global Translation Config 🛠️

AssetsMapper translations installation 📥

You can fetch translations globally by specifying them in the ckeditor5:assets-mapper:install command:

Direct CDN translations configuration ⚙️

You can also configure translations globally in your configuration file. This is useful if you want to load translations for multiple languages at once or set a default language for the editor. Keep in mind that this configuration is only used when loading translations via CDN. If you are using self-hosted setup, translations are handled by your bundler automatically.

Note: For self-hosted setups, translations are handled by your bundler automatically.

Custom translations 🌐

You can also provide custom translations for the editor. This is useful if you want to override existing translations or add new ones. Custom translations can be provided in the preset configuration.

Translation references in config 🔤

You can also reference custom translations directly from your editor configuration by using an object with a $translation key. When the editor is initialized the value will be replaced with the correct string from the loaded translation packs (including any customTranslations defined in your preset).

This is handy if you want to keep plugin labels or other strings inside the YAML and reuse them across presets or languages.

When the editor runs the { $translation: 'MyPluginLabel' } entry will be automatically resolved to the appropriate string for the current UI language, so you don’t need to hard‑code the text in multiple places.

Paragraph-like editing 📄

Paragraph-like editing mode restricts the editor's root to a single block element — by default a <p> — preventing users from inserting multiple top-level block elements (headings, lists, etc.). This is ideal for short-text fields such as article titles, captions, or descriptions: places where you want the richness of inline formatting (bold, italic, links) but a single-paragraph constraint.

The feature is enabled by passing model_element: '$inlineRoot' to the cke5_editor() or cke5_editable() Twig function. This maps the CKEditor 5 model root to the $inlineRoot schema element, which allows only inline content.

[!NOTE] Make sure your preset's toolbar and plugin list does not include block-level items (Heading, List, BlockQuote, etc.) when using model_element: '$inlineRoot', as those commands require block-level schema support that is absent in inline roots.

Classic / Balloon / Inline editor

For single-root editor types, pass model_element: '$inlineRoot' directly to cke5_editor():

The same parameter works with balloon and inline editor types:

If you reuse the inline-text pattern in many places, define a dedicated preset without block-level plugins and reference it by name:

Decoupled editor

For the decoupled editor, pass model_element: '$inlineRoot' to the cke5_editable() function rather than to cke5_editor(). Link the editable to the editor via editor_id:

Multiroot editor

In a multiroot setup each cke5_editable() can independently opt in to paragraph-like mode. Set model_element: '$inlineRoot' only on the roots that should be restricted; leave the others without it (they default to the standard $root):

When the editor initialises, each root whose model_element is set to '$inlineRoot' is registered under that schema element name. You can verify this at runtime via the JavaScript EditorsRegistry:

Forms Integration 🧾

Seamlessly integrate CKEditor 5 with Symfony Forms. The bundle provides a CKEditor5Type that facilitates easy integration. Use CKEditor5Type in your form class to render the editor.

Then in your template:

The editor automatically synchronizes its content with the underlying hidden input field upon form submission.

Editor roots change event 📡

Each editor dispatches a custom ckeditor5:change:data when any of its roots' data changes. This event includes the editor's ID, the editor instance, and the current data of all roots, allowing you to react to content changes in real time. It's safer to mount your listeners on the document.body to ensure they are registered to avoid issues with race conditions during editor initialization.

Custom plugins 🧩

To register a custom plugin, use the CustomEditorPluginsRegistry.

In order to use the plugin you need to extend your config in config/packages/ckeditor5.yaml:

It must be called before the editor is initialized. You can unregister the plugin later by calling the returned function:

If you want to de-register all registered plugins, you can use the unregisterAll method:

Context 🤝

The context feature is designed to group multiple editor instances together, allowing them to share a common context. This is particularly useful in collaborative editing scenarios, where users can work together in real time. By sharing a context, editors can synchronize features such as comments, track changes, and presence indicators across different editor instances. This enables seamless collaboration and advanced workflows in your application.

For more information about the context feature, see the CKEditor 5 Context documentation.

Basic usage 🔧

Define your context in configuration:

And use it in your template:

Voila!

Custom context translations 🌐

Define your custom translations in the configuration:

These translations will be used in the context's editors, overriding the default translations. They are available through locale.t plugin in every context plugin.

Editors and Contexts registry 👀

The package provides two registries: EditorsRegistry and ContextsRegistry. They allow you to watch for changes in registered editors and contexts, get instances directly, or execute logic when a specific editor or context appears.

• mountEffect(id, callback) — executes logic whenever the editor is initialized or restarted. This is the recommended way to implement integrations that must be re-initialized throughout the editor's lifecycle.

• watch(callback) — react whenever registry state changes.

• waitFor(id) — get the instance directly. If it is already registered, the promise resolves immediately.

• execute(id, callback) — run logic immediately if the instance already exists, or later when it appears.

• The same methods are available on ContextsRegistry for shared contexts:

Installer command options ⚙️

The ckeditor5:assets-mapper:install command supports the following options:

Development ⚙️

To start the development environment, run:

The playground app will be available at http://localhost:8000.

Running Tests 🧪

The project includes comprehensive PHP unit tests with 100% code coverage requirement:

Psst... 👀

If you're looking for similar stuff, check these out:

• ckeditor5-livewire Effortless CKEditor 5 integration for Laravel Livewire. Supports dynamic content, localization, and custom builds with minimal setup.

• ckeditor5-phoenix Seamless CKEditor 5 integration for Phoenix Framework. Plug & play support for LiveView forms with dynamic content, localization, and custom builds.

• ckeditor5-rails Smooth CKEditor 5 integration for Ruby on Rails. Works with standard forms, Turbo, and Hotwire. Easy setup, custom builds, and localization support.

Trademarks 📜

CKEditor® is a trademark of CKSource Holding sp. z o.o. All rights reserved. For more information about the license of CKEditor® please visit CKEditor's licensing page.

This package is not owned by CKSource and does not use the CKEditor® trademark for commercial purposes. It should not be associated with or considered an official CKSource product.

License 📜

This project is licensed under the terms of the MIT LICENSE.

This project injects CKEditor 5 which is licensed under the terms of GNU General Public License Version 2 or later. For more information about CKEditor 5 licensing, please see their official documentation.