Symfony Ckeditor 5 Webpack Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require daddl3/symfony-ckeditor-5-webpack
   npm install @ckeditor/ckeditor5-build-classic
   

2. Configure Vite Update vite.config.js to include CKEditor:

   import { defineConfig } from 'vite';
   import { ckeditor5 } from 'daddl3/symfony-ckeditor-5-webpack';
   
   export default defineConfig({
       plugins: [
           ckeditor5({
               build: 'classic',
               config: {
                   toolbar: ['bold', 'italic', 'bulletedList']
               }
           })
       ]
   });
   

3. Twig Integration Add the bundle to config/bundles.php:

   return [
       // ...
       Daddl3\SymfonyCkeditor5WebpackBundle\Daddl3SymfonyCkeditor5WebpackBundle::class => ['all' => true],
   ];
   

4. First Usage In a Twig template:

   {{ ckeditor5('my_editor', {
       'value': 'Initial content',
       'toolbar': ['bold', 'italic']
   }) }}
   

First Use Case: Basic Editor

• Use the ckeditor5 Twig function to render an editor in a form.
• Pass the field name and optional config (e.g., toolbar, height).
• Example:

  <form method="POST">
      {{ form_row(article.content) }}
      {{ ckeditor5('article_content', {
          'toolbar': ['bold', 'italic', 'numberedList', 'blockQuote']
      }) }}
  </form>
  

Implementation Patterns

Workflow: Editor in Forms

1. Symfony Form Integration Use the bundle’s form type for seamless integration:

   use Daddl3\SymfonyCkeditor5WebpackBundle\Form\Type\Ckeditor5Type;
   
   $builder->add('content', Ckeditor5Type::class, [
       'config' => [
           'toolbar' => ['bold', 'italic', 'imageUpload']
       ]
   ]);
   

2. Dynamic Configuration Override editor config per entity or route:

   // In a controller
   $builder->add('description', Ckeditor5Type::class, [
       'config' => $this->getCkeditorConfigForRoute($request->get('_route'))
   ]);
   

3. Asset Management

   • Place CKEditor builds in public/build/ckeditor5/.
   • Configure Vite to output assets to this directory:

     // vite.config.js
     export default defineConfig({
         build: {
             outDir: 'public/build',
             rollupOptions: {
                 output: {
                     entryFileNames: 'ckeditor5/[name].js',
                     chunkFileNames: 'ckeditor5/[name].js',
                 }
             }
         }
     });
     

Integration Tips

• Image Uploads Use the imageUpload plugin with a custom upload adapter (e.g., Symfony Uploader):

  // vite.config.js
  ckeditor5({
      plugins: ['ImageUpload'],
      config: {
          image: {
              upload: {
                  types: ['jpeg', 'png'],
                  url: '/api/ckeditor/upload'
              }
          }
      }
  });
  

• Custom Builds Extend the default build by adding plugins:

  // vite.config.js
  ckeditor5({
      build: {
          plugins: ['@ckeditor/ckeditor5-basic-styles', '@ckeditor/ckeditor5-heading']
      }
  });
  

• Localization Load translations via Vite:

  // vite.config.js
  ckeditor5({
      locale: 'fr',
      additionalLanguages: ['fr']
  });
  

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: CKEditor fails to load if asset paths are incorrect.
   • Fix: Ensure public/build/ckeditor5/ exists and Vite outputs files there. Use absolute paths in Twig:

     {{ asset('build/ckeditor5/ckeditor.js') }}
     

2. Form Data Binding

   • Issue: Editor content may not bind correctly to Symfony forms.
   • Fix: Use the Ckeditor5Type form field and ensure the data attribute matches the field name:

     {{ form_row(article.content) }}
     {{ ckeditor5('article_content') }}  {# Must match field name #}
     

3. Plugin Conflicts

   • Issue: Custom plugins may not load due to missing dependencies.
   • Fix: Verify all required plugins are installed via npm and included in vite.config.js.

Debugging

• Console Errors Check browser console for 404 errors on CKEditor JS/CSS files. Verify Vite’s outDir and asset paths.

• Symfony Profiler Use the Symfony profiler to inspect form data and ensure CKEditor’s output matches the expected format (e.g., HTML-encoded content).

Extension Points

1. Custom Upload Adapters Extend the upload adapter for cloud storage (e.g., AWS S3):

   // vite.config.js
   ckeditor5({
       config: {
           image: {
               upload: {
                   adapter: (loader) => {
                       loader.file.then((file) => {
                           // Custom upload logic (e.g., fetch API)
                       });
                   }
               }
           }
       }
   });
   

2. Editor Presets Create reusable presets in config/packages/daddl3_symfony_ckeditor5_webpack.yaml:

   daddl3_symfony_ckeditor5_webpack:
       presets:
           basic: { toolbar: ['bold', 'italic'] }
           advanced: { toolbar: ['bold', 'italic', 'imageUpload', 'code'] }
   

   Use in forms:

   $builder->add('content', Ckeditor5Type::class, ['preset' => 'advanced']);
   

3. Event Listeners Listen to CKEditor events (e.g., init, change) via JavaScript:

   // In your Vite entry point
   import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
   
   ClassicEditor.create(document.querySelector('#my-editor'), {
       initCallback: editor => {
           editor.model.document.on('change:data', () => {
               console.log('Content changed:', editor.getData());
           });
       }
   });