Ckeditor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require atheon/ckeditor-bundle
   

   Add to config/bundles.php (Symfony 4+):

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

2. Enable the Form Type Register the ckeditor form type in your config/packages/atheon_ckeditor.yaml:

   atheon_ckeditor:
       editor_file: 'ckeditor/ckeditor.js'  # Path to CKEditor JS file
       editor_basepath: '/bundles/atheonckeditor/'  # Base URL for CKEditor assets
   

3. First Usage in a Form

   use Atheon\CKEditorBundle\Form\Type\CKEditorType;
   
   $builder->add('content', CKEditorType::class, [
       'config' => [
           'toolbar' => 'Basic',  // Predefined toolbar or custom config
       ],
   ]);
   

4. Verify Assets Ensure CKEditor assets (ckeditor.js, plugins, skins) are published:

   php bin/console atheon:ckeditor:install
   

First Use Case: Basic Rich Text Field

{{ form_start(form) }}
    {{ form_row(form.content) }}  <!-- Renders CKEditor -->
    <button type="submit">Save</button>
{{ form_end(form) }}

• Output: A CKEditor instance with default toolbar.
• Data Flow: Submitted HTML is sanitized (if configured) and stored in the database.

Implementation Patterns

Common Workflows

1. Customizing CKEditor Config

Override default settings via YAML or PHP:

# config/packages/atheon_ckeditor.yaml
atheon_ckeditor:
    editor_config:
        toolbar:
            - ['Bold', 'Italic']
            - ['NumberedList', 'BulletedList']
        removePlugins: 'elementspath'

2. Dynamic Configuration per Field

Pass inline config to the form type:

$builder->add('bio', CKEditorType::class, [
    'config' => [
        'height' => 300,
        'extraPlugins' => 'codesnippet',
    ],
]);

3. Asset Management

• Publish Assets: Use php bin/console atheon:ckeditor:install to copy CKEditor files to public/bundles/atheonckeditor/.
• Custom Paths: Override editor_basepath in config to point to a CDN or local directory.

4. Integration with Entities

// src/Entity/Article.php
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;

class Article {
    /**
     * @ORM\Column(type="text")
     * @Assert\NotBlank
     */
    private $content;
}

5. Twig Extensions

Access CKEditor assets in Twig:

{{ atheon_ckeditor_assets() }}  <!-- Renders JS/CSS links -->

Integration Tips

Symfony Forms

• Validation: Use Assert\Length or custom constraints on the text field.
• Data Transformers: Handle raw HTML input/output with DataTransformerInterface.

APIs/JSON Responses

• Sanitization: Use Symfony\Component\DomCrawler\Crawler or HTMLPurifier to clean HTML before storage.
• API Response: Serialize CKEditor content as plain text or HTML based on client needs.

Testing

• Unit Tests: Mock the form type and validate config merging.
• Functional Tests: Use Symfony\Panther to test CKEditor UI interactions.

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Missing assets after composer install.
   • Fix: Run php bin/console atheon:ckeditor:install or manually copy files to public/bundles/atheonckeditor/.
   • Tip: Use a symlink for development:

     ln -s vendor/egeloen/ckeditor-bundle/Resources/public/ckeditor public/bundles/atheonckeditor/
     

2. CKEditor Version Mismatch

   • Issue: Bundle expects a specific CKEditor version (e.g., 4.x).
   • Fix: Downgrade or upgrade CKEditor manually and adjust editor_file in config.

3. XSS Vulnerabilities

   • Issue: Storing unsanitized HTML from CKEditor.
   • Fix: Use Symfony\Component\Security\Csrf\TokenManager or libraries like HTMLPurifier:

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

4. Configuration Overrides

   • Issue: Global config not applying to specific fields.
   • Fix: Use config_name in form options to merge configs:

     $builder->add('content', CKEditorType::class, [
         'config_name' => 'custom_config',  // References a named config in YAML
     ]);
     

5. Debugging

   • Tip: Enable debug mode to inspect rendered assets:

     # config/packages/dev/atheon_ckeditor.yaml
     atheon_ckeditor:
         debug: true
     

Tips

1. Performance

   • Lazy Loading: Load CKEditor only on pages where needed using Twig’s {% block javascripts %}.

2. Localization

   • Language Support: Configure CKEditor’s language via config:

     atheon_ckeditor:
         editor_config:
             language: 'fr'
     

3. Advanced Features

   • File Uploads: Integrate with VichUploaderBundle for image uploads:

     'config' => [
         'filebrowserImageUploadUrl' => '/upload/image',
         'filebrowserBrowseUrl' => '/browser',
     ],
     

   • Plugins: Enable additional plugins (e.g., ckfinder, mathjax) by including them in extraPlugins.

4. Upgrade Path

   • Symfony 5+: Ensure compatibility by checking symfony/dependency-injection constraints in composer.json.

5. Extension Points

   • Custom Form Type: Extend CKEditorType for reusable configurations:

     class CustomCKEditorType extends CKEditorType {
         public function configureOptions(OptionsResolver $resolver) {
             $resolver->setDefaults([
                 'config' => [
                     'toolbar' => ['CustomToolbar'],
                 ],
             ]);
         }
     }
     

6. CI/CD

   • Asset Handling: Automate asset installation in CI (e.g., GitHub Actions):

     - run: php bin/console atheon:ckeditor:install --no-debug