Getting Started

Minimal Setup

Installation:

composer require egeloen/ckeditor-bundle

Add the bundle to config/bundles.php:

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

Configuration: Enable the bundle in config/packages/ivory_ck_editor.yaml:

ivory_ck_editor:
    default_config: my_default_config
    configs:
        my_default_config:
            toolbar: [ 'bold', 'italic', 'numberedList', 'bulletedList' ]
            filebrowserUploadUrl: /upload
            filebrowserUploadHandler: IvoryCKEditorBundle:Upload:upload

First Use Case: Add the CKEditor field to a Symfony form:

use Ivory\CKEditorBundle\Form\Type\CKEditorType;

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

Upload Handler (if needed): Ensure your upload directory is writable and configure the upload controller (provided by the bundle) to handle file uploads.

Implementation Patterns

Common Workflows

1. Basic Integration with Forms

Use CKEditorType in Symfony forms for rich-text fields.

Example:

$builder->add('description', CKEditorType::class, [
    'config' => 'rich_text_config',
    'attr' => ['class' => 'ckeditor-full'],
]);

2. Custom Configurations

Define multiple editor configurations in ivory_ck_editor.yaml:

configs:
    basic_config:
        toolbar: ['bold', 'italic']
        height: 200
    advanced_config:
        toolbar: ['bold', 'italic', 'image', 'codeSnippet']
        extraPlugins: 'codesnippet'

Reference them in forms:

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

3. Dynamic Configurations

Override configurations programmatically:

$builder->add('content', CKEditorType::class, [
    'config' => function (FormInterface $form, array $options) {
        return [
            'toolbar' => ['bold', 'italic', 'link'],
            'filebrowserImageUploadUrl' => $this->generateUrl('app_upload_image'),
        ];
    },
]);

4. Asset Management

Customize CKEditor assets (CSS/JS) by overriding the bundle’s templates:

{# templates/IvoryCKEditor/ckeditor.html.twig #}
{{ parent() }}
{{ ckeditor_extra_js('custom_plugin.js') }}

5. Handling Uploads

Extend the default upload handler to validate or process files:

// src/Controller/UploadController.php
use Ivory\CKEditorBundle\Controller\UploadController as BaseUploadController;

class UploadController extends BaseUploadController
{
    public function uploadAction(Request $request)
    {
        $response = parent::uploadAction($request);
        // Add custom logic (e.g., resize images)
        return $response;
    }
}

Update the config:

filebrowserUploadHandler: App\Controller\UploadController::uploadAction

6. Twig Integration

Use the ckeditor Twig function to render editors directly in templates:

{{ ckeditor(form.content, {
    'config': 'basic_config',
    'attr': {'class': 'compact-editor'}
}) }}

Integration Tips

Symfony Flex Compatibility

The bundle works seamlessly with Symfony Flex. No manual wiring is required beyond the config/bundles.php step.

Asset Versioning

Enable Symfony’s asset versioning to cache-bust CKEditor assets:

# config/packages/twig.yaml
twig:
    paths: ['%kernel.project_dir%/templates']
    globals:
        ckeditor_version: '%kernel.cache_dir%/ckeditor_version.txt'

Debugging Assets

Clear the cache after updating CKEditor configurations:
```
php bin/console cache:clear
```

Laravel-Specific Adaptation (Symfony Bridge)

If using Laravel with Symfony components (e.g., via laravel/symfony-bridge), ensure:
- The bundle is registered in config/app.php under extra.bundles.
- The ivory_ck_editor.yaml config is merged into Laravel’s configuration system.

Gotchas and Tips

Pitfalls

1. File Upload Permissions

Ensure the upload directory (default: %kernel.project_dir%/web/uploads/ckeditor) is writable:
```
mkdir -p web/uploads/ckeditor
chmod -R 775 web/uploads/ckeditor
```
Symptom: Uploads fail silently or return 500 errors.

2. Missing Upload Handler Route

If using custom upload handlers, ensure the route is defined in routing.yaml:

app_upload:
    path: /upload
    methods: POST
    defaults: { _controller: 'App\Controller\UploadController::uploadAction' }

Symptom: "File upload failed" errors in the CKEditor UI.

3. Asset Loading Issues

If CKEditor assets (JS/CSS) fail to load:
- Verify the assets key in config/packages/ivory_ck_editor.yaml points to the correct path:
```
assets:
    base_url: /bundles/ivoryckeditor
```
- Symptom: Blank editor or broken toolbar.

4. Configuration Overrides

Avoid overriding the entire config in forms. Use config or config_name to reference existing configs:

// ❌ Avoid (overwrites everything)
$builder->add('content', CKEditorType::class, [
    'config' => ['toolbar' => ['bold']] // Loses other settings
]);

// ✅ Prefer
$builder->add('content', CKEditorType::class, ['config' => 'my_config']);

5. Plugin Conflicts

CKEditor plugins (e.g., codesnippet) must be installed via npm or included manually in the assets directory.
Symptom: Plugin buttons appear but don’t work.
Fix: Ensure plugins are listed in extraPlugins and their JS/CSS are loaded.

Debugging Tips

1. Enable Debug Mode

Set debug: true in config/packages/ivory_ck_editor.yaml to log configuration issues:
```
debug: true
```
Check Symfony’s debug toolbar for errors.

2. Check Browser Console

Open DevTools (F12) to inspect:
- Network requests for missing assets.
- JS errors (e.g., CKEDITOR is not defined).

3. Validate Config

Use the ivory_ck_editor:validate command to check configs:
```
php bin/console ivory:ckeditor:validate
```

4. Clear Cache Aggressively

If changes aren’t reflected:

php bin/console cache:clear
rm -rf var/cache/*

Extension Points

1. Custom Upload Handlers

Extend Ivory\CKEditorBundle\Controller\UploadController to add validation or processing:

use Ivory\CKEditorBundle\Controller\UploadController as BaseUploadController;

class CustomUploadController extends BaseUploadController
{
    public function uploadAction(Request $request)
    {
        $response = parent::uploadAction($request);
        $file = $response->getFile();
        // Add custom logic (e.g., resize images)
        return $response;
    }
}

2. Dynamic Configs via Services

Create a service to generate configs dynamically:

# config/services.yaml
services:
    App\Service\CKEditorConfigBuilder:
        arguments:
            $defaultConfig: '%ivory_ck_editor.configs.default%'

// src/Service/CKEditorConfigBuilder.php
class CKEditorConfigBuilder
{
    public function build(array $options): array
    {
        return array_merge($this->defaultConfig, $options);
    }
}

Use it in forms:

$builder->add('content', CKEditorType::class, [
    'config' => $this->container->get(CKEditorConfigBuilder::class)->build(['height' => 300]),
]);

3. Twig Extensions

Add custom Twig

Ckeditor Bundle Laravel Package