Getting Started

Minimal Setup

Installation:
```
composer require drymek/ckeditor-bundle
```
(Note: The README references a deprecated vendors command; use composer update instead.)

Enable Bundle: Add to config/bundles.php:

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

Asset Installation:

php artisan assets:install public --symlink

Basic Usage: In a form type, use the CkeditorType:

use Trsteel\CkeditorBundle\Form\CkeditorType;

$builder->add('content', CkeditorType::class);

First Test: Create a simple form controller to render a CKEditor field and submit it.

Key Configuration File

Locate config/packages/trsteel_ckeditor.yaml (auto-generated after installation). Defaults:

trsteel_ckeditor:
    toolbar: ['document', 'clipboard', 'editing', 'basicstyles', 'paragraph', 'links', 'insert', 'styles', 'tools']
    # ... (see full config below)

Implementation Patterns

1. Form Integration

Dynamic Toolbar Configuration: Override toolbar per field:

$builder->add('bio', CkeditorType::class, [
    'config' => [
        'toolbar' => ['document', 'basicstyles', 'links'],
    ],
]);

File Uploads: Configure uploads in config/packages/trsteel_ckeditor.yaml:

trsteel_ckeditor:
    filebrowser_upload_url: '/upload'  # Route for uploads
    filebrowser_upload_handler: 'Symfony\Bundle\FrameworkBundle\Routing\Router'  # Service for handling

2. Customizing Editor Behavior

Presets: Create a custom type extending CkeditorType:

use Trsteel\CkeditorBundle\Form\CkeditorType;

class AdminCkeditorType extends CkeditorType {
    public function getParent() {
        return CkeditorType::class;
    }

    public function getConfig() {
        return [
            'toolbar' => ['document', 'clipboard', 'editing', 'basicstyles'],
            'extraPlugins' => 'image2',
        ];
    }
}

Advanced Config: Pass full CKEditor config:

$builder->add('description', CkeditorType::class, [
    'config' => [
        'height' => 400,
        'width' => '100%',
        'filebrowserUploadUrl' => '/api/upload',
        'extraPlugins' => 'divarea,image2',
    ],
]);

3. Handling Uploads

Route Setup: Define a route for uploads (e.g., upload_ckeditor):

# config/routes.yaml
upload_ckeditor:
    path: /upload
    controller: Trsteel\CkeditorBundle\Controller\UploadController::upload

Storage: Configure storage in config/packages/trsteel_ckeditor.yaml:

trsteel_ckeditor:
    upload_dir: '%kernel.project_dir%/public/uploads/ckeditor'
    upload_allowed_mime: ['image/jpeg', 'image/png', 'application/pdf']

Custom Upload Handler: Bind a service to handle uploads:

# config/services.yaml
services:
    Trsteel\CkeditorBundle\Service\UploadHandler:
        arguments:
            $uploadDir: '%kernel.project_dir%/public/uploads/custom'

4. Twig Integration

Render CKEditor in Twig:

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

Inline Editing: Use ckeditor_inline type:

$builder->add('inline_content', CkeditorType::class, [
    'inline' => true,
]);

Gotchas and Tips

1. Common Pitfalls

Asset Symlink Issues: If CKEditor assets fail to load, ensure symlinks are set:
```
php artisan assets:install public --symlink --no-debug
```
Clear cache if needed:
```
php artisan cache:clear
```

CSRF Token Mismatch: Uploads may fail due to missing CSRF tokens. Ensure your upload route includes:

// UploadController.php
public function upload(Request $request) {
    $request->headers->set('X-Requested-With', 'XMLHttpRequest');
    // ...
}

File Permissions: Verify upload_dir is writable:

chmod -R 775 %kernel.project_dir%/public/uploads/ckeditor

2. Debugging

Console Errors: Check browser console for 403/404 on uploads. Validate:
- Upload route exists.
- filebrowser_upload_url matches the route.
- MIME types are allowed in upload_allowed_mime.
CKEditor Not Loading: Clear browser cache or test in incognito mode. Verify:
- Assets are symlinked (public/bundles/trsteelckeditor/ exists).
- No JavaScript errors block initialization.
Configuration Overrides: Use dump(config('trsteel_ckeditor')) to verify active config.

3. Extension Points

Custom Plugins: Add plugins via extraPlugins in config:
```
trsteel_ckeditor:
    extraPlugins: 'image2,widget'
```
Ensure plugins are included in assets/install (e.g., ckeditor/plugins/image2/).

Event Listeners: Subscribe to upload events:

// src/EventListener/CkeditorUploadListener.php
use Trsteel\CkeditorBundle\Event\UploadEvent;

public function onUpload(UploadEvent $event) {
    $event->setFilePath('custom/' . $event->getFile()->getClientOriginalName());
}

services:
    App\EventListener\CkeditorUploadListener:
        tags:
            - { name: kernel.event_listener, event: trsteel.ckeditor.upload, method: onUpload }

Twig Extensions: Extend Twig for dynamic configs:

// src/Twig/CkeditorExtension.php
public function getEditorConfig($configKey) {
    return config("trsteel_ckeditor.{$configKey}");
}

services:
    App\Twig\CkeditorExtension:
        tags: ['twig.extension']

4. Performance Tips

Lazy-Load Assets: Use assets:install --no-debug in production to avoid unnecessary files.
Minify CKEditor: Configure assets:install to minify JS/CSS:
```
php artisan assets:install public --symlink --env=prod
```

Cache Config: Override config per environment:

# config/packages/trsteel_ckeditor_prod.yaml
trsteel_ckeditor:
    extraPlugins: []
    height: 300  # Smaller editor in production

5. Laravel-Specific Notes

Route Naming: Laravel’s router may conflict with Symfony’s. Use named routes:

# config/routes.yaml
upload_ckeditor:
    path: /ckeditor/upload
    controller: Trsteel\CkeditorBundle\Controller\UploadController::upload
    name: ckeditor_upload

Reference in config:

trsteel_ckeditor:
    filebrowser_upload_url: '{{ path("ckeditor_upload") }}'

Form Theming: Extend Laravel’s form theme to include CKEditor classes:

{# resources/views/vendor/laravel/form/ckeditor.html.twig #}
<textarea {{ block('widget_attributes') }} class="ckeditor"></textarea>

Validation: Validate file uploads in a FormEventSubscriber:

public function postSubmit(FormEvent $event) {
    $form = $event->getForm();
    $data = $event->getData();

    if ($form->has('content') && $data['content'] && strpos($data['content'], 'invalid_file') !== false) {
        $form->addError($form->get('content'), new \Symfony\Component\Form\Exception\UnexpectedTypeException($data['content'], 'string'));
    }
}

Ckeditor Bundle Laravel Package