Ckfinder Symfony Bundle Laravel Package

Getting Started

First, calibrate expectations: this is a 5-star, zero-dependent, archived bundle. "Getting started" for a team means deciding whether to start. Treat it as a reference implementation of the CKFinder 3 connector protocol on Symfony + Flysystem 2, not as a dependency you can lean on for years.

If you proceed:

1. Confirm your Flysystem major version. The bundle targets Flysystem 2. Laravel 9+ and modern Symfony ship Flysystem 3, so you will be installing league/flysystem:^2 alongside — or, in a Laravel app, you are effectively building a parallel storage stack. Pin exact versions in composer.json; with an archived repo there is no patch release coming when the next Flysystem/Symfony minor breaks an interface.
2. Install and enable:

   composer require kocal/ckfinder-symfony-bundle
   

   // config/bundles.php
   Kocal\Bundle\CKFinderBundle\CKFinderBundle::class => ['all' => true],
   

3. Read the source before the README. The two files that matter are the bundle's DependencyInjection/Configuration.php (the authoritative list of config keys — README drift is common in low-traffic bundles) and the connector controller. Everything you can configure is visible there in a few hundred lines.
4. Wire a Flysystem adapter as a service. The bundle references backends by service id, so the first real step is registering your adapter(s):

   // config/services.yaml
   services:
       ckfinder.adapter.public:
           class: League\Flysystem\Local\LocalFilesystemAdapter
           arguments: ['%kernel.project_dir%/public/uploads']
   

5. First use case: a single Images resource type backed by that local adapter, with an authentication service that gates access, and CKFinder's connectorPath pointed at the route the bundle registers (typically /ckfinder/connector). Load an editor, click "Browse Server", confirm files list. That round trip proves config, auth, and adapter wiring in one shot.

Note the licensing gap early: the bundle is the backend connector only. CKFinder 3's frontend JS/CSS is commercial and is downloaded separately from CKSource — it is not shipped here. Budget for that before you promise anyone a file browser.

Implementation Patterns

Authentication as the primary extension point. The bundle expects you to implement its authentication interface as a Symfony service. That service is your entire security model — CKFinder calls it on every connector request, and it is the only thing standing between an attacker and your storage. Put real logic there:

final class CkfinderAuth implements AuthenticationInterface
{
    public function authenticate(): bool
    {
        $user = $this->security->getUser();
        return $user !== null && $user->hasRole('ROLE_EDITOR');
    }
}

Per-tenant / per-user folders are the pattern people actually want. Do it by defining the Flysystem adapter's root dynamically (a service that resolves a path from the request/token) rather than trying to pass paths through CKFinder config. Keep one resource type per kind of content (Images, Documents, PrivateFiles), each with its own backend and, ideally, its own authentication rules — this compartmentalizes blast radius far better than ACL tuning inside CKFinder.

Public vs private split. Two adapters: one rooted under public/ for content that ends up in HTML, one rooted outside the web root for originals. Editors browse both; only the public one is ever linked from the rendered page. This is the single highest-value structural decision you'll make with this bundle.

Editor integration. For CKEditor 4, set config.filebrowserBrowseUrl / filebrowserUploadUrl to the connector route. For CKEditor 5, you need the CKFinder upload adapter plugin and connectorPath; the plugin is part of a CKEditor 5 build and does not ship with this bundle. For Symfony forms/EasyAdmin, wrap the editor field once in a Twig form theme so the connector path isn't duplicated across templates.

Local development workflow. Point a filesystem adapter at var/uploads-dev and a second config block at S3 for prod, selected by when@dev / when@prod. Because the backend is Flysystem, the same code path serves both — that parity is the bundle's best genuine feature.

Gotchas and Tips

• Archived means frozen. No security patches. If you ship this, fork it into your VCS vendor namespace or, better, write a ~150-line controller that speaks the connector protocol over Flysystem 3. The protocol is small; the maintenance risk of the dependency is larger than the code it saves.
• Flysystem 2 vs 3 is the #1 breakage. Laravel's filesystem, Symfony's flysystem-bundle, and most adapters now assume v3. Installing v2 can silently downgrade shared packages. Run composer why league/flysystem after install and confirm nothing else moved.
• NOASSERTION license. The repo's own license is unclear from metadata, and CKFinder 3 itself is commercially licensed. Get this cleared before production — an unclear license on an archived upload endpoint is not a "we'll fix it later" item.
• Generic client errors hide real causes. CKFinder's JS reports "Invalid request" / "The file browser is disabled for security reasons" for what are usually three distinct things: auth service returning false, adapter service id typo, or a resource type name mismatch between JS config and PHP config. Debug in this order: Symfony profiler for the connector request → var/log/dev.log → the connector's raw response body in the network tab.
• Uploads are the attack surface. Regardless of what the bundle validates, enforce: extension allowlist after MIME sniffing, random filenames, no execution in the upload directory (php_flag engine off / S3 ACL private), and serve public files through a route or CDN rather than raw Apache/Nginx passthrough. Double extensions (.php.jpg) and SVG (stored XSS) are the classics.
• Thumbnails need an image backend. CKFinder's thumbnail generation wants GD or Imagick; without it you get full-size images in the grid and confusing UI lag on large folders. Verify gd or imagick in php -m before blaming the bundle.
• Cache the config. In dev you'll re-read config/packages/ckfinder.php constantly; remember it's compiled into the container, so bin/console cache:clear after any resource-type change — resource types that "don't appear" are usually stale container cache.
• Extension points are thin by design. Beyond authentication and adapters there isn't much to hook. If you find yourself wanting to intercept the connector response, that's the signal you should own the controller instead of the bundle.