Ckeditor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require friendsofsymfony/ckeditor-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       FriendsOfSymfony\CKEditorBundle\FOSCKEditorBundle::class => ['all' => true],
   ];
   

3. Configure CKEditor in config/packages/fos_ck_editor.yaml:

   fos_ck_editor:
       base_path: /bundles/fosckeditor
       config: config/ckeditor.yml
   

4. Add CKEditor to a Form (Symfony Form):

   use FriendsOfSymfony\CKEditorBundle\Form\Type\CKEditorType;
   
   $builder->add('content', CKEditorType::class, [
       'config' => ['toolbar' => 'Full'],
   ]);
   

5. Clear Cache:

   php bin/console cache:clear
   

First Use Case

Replace a plain textarea with a rich-text editor in a blog post form:

{{ form_row(form.content) }}

The editor will render automatically, with the content saved as HTML in your database.

Implementation Patterns

Common Workflows

1. Basic Integration with Forms

• Use CKEditorType in Symfony forms for fields requiring rich text.
• Customize toolbar presets (e.g., 'toolbar' => ['Basic', 'Full']) to control editor features.
• Example:

  $builder->add('description', CKEditorType::class, [
      'config' => [
          'toolbar' => ['Bold', 'Italic', 'NumberedList', 'BulletedList'],
          'removePlugins' => 'elementspath',
      ],
  ]);
  

2. Dynamic Configuration per Field

• Override default config per form field using the config option.
• Example: Disable images for a specific field:

  $builder->add('bio', CKEditorType::class, [
      'config' => ['removePlugins' => 'image'],
  ]);
  

3. Asset Management

• Place CKEditor assets in public/bundles/fosckeditor/ (default base_path).
• Customize asset paths in fos_ck_editor.yaml:

  fos_ck_editor:
      base_path: /custom/path
  

4. Twig Integration

• Render the editor directly in Twig:

  {{ form_widget(form.content, {'attr': {'class': 'ckeditor'}}) }}
  

• Use fos_ck_editor_include_javascript to load CKEditor in non-form contexts:

  {{ fos_ck_editor_include_javascript('my_editor') }}
  <textarea id="my_editor"></textarea>
  

5. Custom Toolbar Presets

• Define reusable toolbars in config/ckeditor.yml:

  toolbar:
      Basic: [Bold, Italic, Underline]
      Full: [Bold, Italic, Underline, 'NumberedList', 'BulletedList', 'Blockquote']
  

• Reference them in forms:

  $builder->add('content', CKEditorType::class, ['config' => ['toolbar' => 'Full']]);
  

6. Handling Uploads

• Configure file uploads via config/ckeditor.yml:

  filebrowserUploadUrl: /upload
  filebrowserUploadHandler: custom_handler
  

• Implement a controller to handle uploads (e.g., using SymfonyUploaderBundle or custom logic).

7. Versioning and Updates

• Pin the bundle version in composer.json for stability:

  "friendsofsymfony/ckeditor-bundle": "^2.0"
  

• Check the changelog for breaking changes.

Integration Tips

Symfony Forms

• Use CKEditorType as a drop-in replacement for TextareaType where rich text is needed.
• Validate HTML output with a validator (e.g., Symfony\Component\Validator\Constraints\Html).

Asset Pipeline

• Ensure base_path in fos_ck_editor.yaml points to a writable directory.
• For production, use a CDN or bundle assets via Webpack Encore.

Security

• Sanitize HTML output before rendering (e.g., with Symfony\Component\DomCrawler\Crawler or HTMLPurifier).
• Restrict file uploads to safe formats (e.g., .jpg, .png) and validate sizes.

Performance

• Lazy-load CKEditor by initializing it via JavaScript only when needed:

  document.addEventListener('DOMContentLoaded', function() {
      ClassicEditor.create(document.querySelector('#my_editor'));
  });
  

Gotchas and Tips

Pitfalls

1. Asset Path Issues

• Symptom: CKEditor fails to load with 404 errors.
• Cause: Incorrect base_path in fos_ck_editor.yaml or missing assets.
• Fix:
  • Verify public/bundles/fosckeditor/ exists and is writable.
  • Run php bin/console assets:install if using Symfony’s asset system.
  • Clear cache after changes:

    php bin/console cache:clear
    

2. Configuration Overrides

• Symptom: Custom config/ckeditor.yml settings are ignored.
• Cause: The bundle may be using default values due to incorrect file placement or syntax.
• Fix:
  • Ensure config/ckeditor.yml is in the correct location (e.g., config/packages/fos_ck_editor.yml for Symfony 4.4+).
  • Validate YAML syntax (e.g., use yaml.lint or an online validator).

3. CSRF Token Mismatch

• Symptom: File uploads fail with CSRF errors.
• Cause: Missing _csrf_token in upload requests.
• Fix:
  • Ensure your upload handler includes CSRF protection:

    // In your upload controller
    $this->denyAccessUnlessGranted('IS_AUTHENTICATED', null, 'Cannot upload without authentication');
    

  • Use Symfony’s csrf_token helper in Twig for hidden fields.

4. HTML Sanitization

• Symptom: Malicious HTML is saved to the database.
• Cause: Lack of input validation.
• Fix:
  • Use a validator like Html constraint:

    use Symfony\Component\Validator\Constraints as Assert;
    
    $builder->add('content', CKEditorType::class, [
        'constraints' => [new Assert\Html()],
    ]);
    

  • Or sanitize output with HTMLPurifier:

    $purifier = new \HTMLPurifier();
    $cleanHtml = $purifier->purify($dirtyHtml);
    

5. JavaScript Conflicts

• Symptom: CKEditor fails to initialize due to $ or jQuery conflicts.
• Cause: Other libraries using the same namespace.
• Fix:
  • Use jQuery.noConflict() if jQuery is loaded.
  • Initialize CKEditor after DOM is ready:

    document.addEventListener('DOMContentLoaded', function() {
        ClassicEditor.create(document.querySelector('#my_editor'));
    });
    

6. File Upload Permissions

• Symptom: Uploads fail silently or return errors.
• Cause: Incorrect file permissions on the upload directory.
• Fix:
  • Ensure the upload directory (e.g., public/uploads/) is writable:

    chmod -R 775 public/uploads/
    

  • Check PHP error logs for specific errors (e.g., failed to open stream).

7. Toolbar Configuration Errors

• Symptom: Toolbar buttons are missing or misconfigured.
• Cause: Invalid toolbar preset names or typos.
• Fix:
  • Verify preset names match those defined in config/ckeditor.yml.
  • Use valid CKEditor plugin names (e.g., Bold, not bold).

Debugging Tips

1. Check Browser Console

• Open DevTools (F12) and inspect the Console and Network tabs for:
  • 404 errors (missing assets).
  • JavaScript errors (e.g., CKEDITOR is not defined).
  • Failed upload requests (CSRF, permissions).

2. Enable Debug Mode

• Set APP_DEBUG=true in .env to see detailed errors.
• Check Symfony’s profiler for form/validation issues.

3. Log Configuration

• Dump the active CKEditor config in Twig:

  {% if app.debug %}
      <pre>{{ dump(f