Ckeditor Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require trsteel/ckeditor-bundle
   

   Add to bundles.php (Symfony 5+):

   return [
       Trsteel\CkeditorBundle\TrsteelCkeditorBundle::class => ['all' => true],
   ];
   

2. Install Assets

   php bin/console assets:install public
   

3. First Use Case Add to a form type:

   use Trsteel\CkeditorBundle\Form\Type\CkeditorType;
   
   $builder->add('content', CkeditorType::class);
   

   Render in a template:

   {{ form_row(form.content) }}
   

Key Files to Review

• config/packages/trsteel_ckeditor.yaml (auto-generated after installation)
• templates/trsteel_ckeditor/editor.html.twig (customization entry point)
• assets/ckeditor/ (asset directory for JS/CSS overrides)

Implementation Patterns

Common Workflows

1. Basic Integration

   // src/Form/ArticleType.php
   $builder->add('body', CkeditorType::class, [
       'config' => [
           'toolbar' => ['bold', 'italic', 'numberedList'],
       ],
   ]);
   

2. Dynamic Configuration Use dependency injection to pass runtime config:

   $builder->add('description', CkeditorType::class, [
       'config' => $this->getCkeditorConfig($userRole),
   ]);
   

3. Asset Overrides Extend default assets via assets.json:

   {
       "ckeditor": {
           "js": ["path/to/custom-plugin.js"],
           "css": ["path/to/custom-styles.css"]
       }
   }
   

4. Data Transformers Enable HTML sanitization in config/packages/trsteel_ckeditor.yaml:

   trsteel_ckeditor:
       transformers: ['html_purifier']
   

Integration Tips

• Symfony UX Turbo: Works seamlessly with Turbo for SPA-like behavior.

  {{ form_row(form.content, {'attr': {'data-turbo-frame': '_self'}}) }}
  

• API Projects: Use data_class with ApiPlatform entities:

  $builder->add('markdown', CkeditorType::class, [
      'mapped' => false,
      'attr' => ['class' => 'markdown-input'],
  ]);
  

• Custom Toolbars: Define reusable toolbars in config:

  trsteel_ckeditor:
      toolbars:
          basic: ['bold', 'italic', 'link']
          advanced: ['*', 'numberedList', 'blockQuote']
  

  Then reference:

  'config' => ['toolbar' => 'advanced']
  

Gotchas and Tips

Common Pitfalls

1. Asset Pipeline Issues

   • Symptom: CKEditor fails to load.
   • Fix: Ensure assets:install is run and symlinks are correct.

     php bin/console assets:install public --symlink
     

   • Debug: Check browser console for 404s on /build/ckeditor.js.

2. Configuration Overrides

   • Symptom: Custom toolbar settings ignored.
   • Fix: Use config:dump-reference to verify precedence:

     php bin/console config:dump-reference TrsteelCkeditorBundle
     

   • Tip: Bundle config is merged in this order: defaults → params → services → YAML.

3. Data Transformer Conflicts

   • Symptom: HTML entities not decoded/encoded.
   • Fix: Explicitly set transformers in form options:

     $builder->add('content', CkeditorType::class, [
         'transformers' => ['html_purifier', 'html_entity_decode'],
     ]);
     

4. Twig Template Overrides

   • Symptom: Custom editor template not loaded.
   • Fix: Override the correct path:

     {# templates/trsteel_ckeditor/editor.html.twig #}
     

   • Debug: Use {{ dump(app.request.uri) }} to verify template resolution.

Debugging Tips

• Enable CKEditor Debug Mode:

  trsteel_ckeditor:
      debug: true
  

  Logs config and asset paths to Symfony profiler.

• Check for JavaScript Errors:

  php bin/console debug:assets
  

  Verify ckeditor entry exists and is built.

Extension Points

1. Custom Plugins Add plugins via assets.json:

   {
       "ckeditor": {
           "plugins": ["your_plugin"]
       }
   }
   

   Then include in toolbar:

   'config' => ['toolbar' => ['your_plugin']]
   

2. Event Listeners Subscribe to ckeditor.init event for runtime modifications:

   // src/EventListener/CkeditorListener.php
   public function onCkeditorInit(CkeditorEvent $event) {
       $event->getConfig()->extraPlugins = 'your_plugin';
   }
   

   Register in services.yaml:

   services:
       App\EventListener\CkeditorListener:
           tags:
               - { name: 'kernel.event_listener', event: 'ckeditor.init' }
   

3. Database Storage For large content, use DoctrineExtensions with Sluggable:

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\Slug(fields={"title"})
    */
   private $slug;