Ckfinder Symfony Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require bsdrazor/ckfinder-symfony-bundle
   

   Ensure your config/bundles.php includes CKSource\CKFinderBundle\CKSourceCKFinderBundle::class.

2. Download CKFinder Run the CLI command to fetch the distribution:

   php bin/console ckfinder:download
   

   Verify the files are in vendor/cksource/ckfinder-symfony-bundle/Resources/public/.

3. Enable Routing Create config/routes/ckfinder.yaml:

   ckfinder_connector:
       resource: "@CKSourceCKFinderBundle/Resources/config/routing.yml"
       prefix: /ckfinder
   

   Clear cache:

   php bin/console cache:clear
   

4. Configure Storage Create a writable directory (e.g., public/userfiles) and update config/packages/ckfinder.yaml:

   ckfinder:
       storage:
           directory: "%kernel.project_dir%/public/userfiles"
   

5. First Use Case Integrate with CKEditor in a Twig template:

   {{ ckeditor_widget('article_content', {
       'filebrowserImageBrowseUrl': '/ckfinder/browser/browse.php?type=Images',
       'filebrowserImageUploadUrl': '/ckfinder/core/connector/php/upload.php?type=Images',
       'filebrowserBrowseUrl': '/ckfinder/browser/browse.php?type=Files',
       'filebrowserUploadUrl': '/ckfinder/core/connector/php/upload.php?type=Files'
   }) }}
   

Implementation Patterns

Workflows

1. File Management

   • Uploads: Use the connector endpoints (/ckfinder/core/connector/php/upload.php) for handling file uploads from CKEditor.
   • Browsing: Expose the browser endpoint (/ckfinder/browser/browse.php) for file selection dialogs.
   • Permissions: Restrict access via Symfony security (e.g., annotate routes with @IsGranted("ROLE_USER")).

2. Custom Storage Backends Override the default directory storage by implementing CKSource\CKFinderBundle\Storage\StorageInterface and configure it in config/packages/ckfinder.yaml:

   ckfinder:
       storage:
           class: App\Service\CustomStorageService
   

3. Asset Optimization

   • Use Symfony’s asset system to version CKFinder JS/CSS:

     php bin/console assets:install public
     

   • Enable debug mode in config/packages/ckfinder.yaml for development:

     ckfinder:
         debug: true
     

4. Twig Integration Embed CKFinder in forms or templates:

   {% set ckfinderConfig = {
       'uploadUrl': path('ckfinder_upload', {'type': 'Files'}),
       'browseUrl': path('ckfinder_browse', {'type': 'Files'})
   } %}
   {{ ckeditor_widget('field_name', ckfinderConfig) }}
   

5. API-Driven Uploads For non-CKEditor uploads, use the connector directly via HTTP requests:

   // Example: Upload via fetch API
   const formData = new FormData();
   formData.append('upload', file);
   fetch('/ckfinder/core/connector/php/upload.php?type=Files', {
       method: 'POST',
       body: formData
   });
   

Gotchas and Tips

Pitfalls

1. License Compliance

   • The bundle does not include CKFinder’s core files (due to licensing). Always run ckfinder:download to fetch the latest version.
   • Verify the userfiles directory is writable by the web server user (e.g., www-data or nginx).

2. Routing Conflicts

   • Ensure the prefix in ckfinder.yaml doesn’t clash with existing routes. Test with:

     php bin/console debug:router | grep ckfinder
     

3. CORS Issues

   • If using CKFinder with a separate frontend (e.g., React/Vue), configure CORS in Symfony:

     # config/packages/nelmio_cors.yaml
     nelmio_cors:
         paths:
             '^/ckfinder/':
                 allow_origin: ['*']
                 allow_methods: ['GET', 'POST']
     

4. Debugging Uploads

   • Check the Symfony profiler (/_profiler) for failed uploads. Common causes:
     • Missing enctype="multipart/form-data" in forms.
     • Incorrect type parameter (e.g., Files vs. Images).
     • File size limits (adjust upload_max_filesize in php.ini if needed).

5. Symfony 6+ Quirks

   • The bundle assumes Symfony 6+. For older versions, use the v3 branch.
   • If using Symfony UX, ensure CKEditor is loaded after CKFinder’s JS:

     {{ ckeditor_script() }}
     {{ ckfinder_script() }}
     

Tips

1. Environment-Specific Config Override settings per environment (e.g., config/packages/ckfinder_dev.yaml):

   ckfinder:
       debug: true
       storage:
           directory: "%kernel.project_dir%/public/userfiles_dev"
   

2. Custom Connector Logic Extend the connector by overriding the CKSourceCKFinderBundle\Connector\Connector class and update the service in config/services.yaml:

   services:
       CKSourceCKFinderBundle\Connector\Connector:
           class: App\Connector\CustomConnector
   

3. File Type Restrictions Restrict uploads by file type in config/packages/ckfinder.yaml:

   ckfinder:
       allowed_file_types:
           Images: ['jpg', 'png', 'gif']
           Files: ['pdf', 'docx', 'txt']
   

4. Logging Enable debug logging to track connector activity:

   ckfinder:
       debug: true
   

   Check logs at var/log/dev.log.

5. Docker Setup For Dockerized environments, ensure volumes are mounted for userfiles:

   # docker-compose.yml
   services:
       app:
           volumes:
               - ./public/userfiles:/var/www/public/userfiles