Ckfinder Laravel Package

Getting Started

1. Install and confirm the provider is registered

composer require jonlil/ckfinder

On Laravel 5.5+ the service provider is auto-discovered. On older versions add Jonlil\CKFinder\CKFinderServiceProvider::class to config/app.php. Because this package has near-zero adoption, pin the exact version in composer.json and commit composer.lock before you do anything else.

2. Publish and read the config

php artisan vendor:publish --provider="Jonlil\CKFinder\CKFinderServiceProvider"

Open config/ckfinder.php first. That file is the package: the auth callback, connector route path, upload baseUrl/baseDir, and the CKFinder settings array (allowed extensions, max size, ACLs). Then read src/ — the wrapper is small and you should be able to read the whole thing in an hour. If you cannot, do not adopt it.

3. Verify the moving pieces exist before wiring the frontend

Check in this order:

• The connector route appears in php artisan route:list and sits behind auth middleware.
• The route loads (as an authenticated admin) without a 500 — that proves CKFinder's PHP connector is actually installed and reachable.
• You can list one directory and upload one file into it from CKFinder's own UI.
• Only then wire the CKEditor "Browse Server" button to the connector URL.

First real use case: an admin-only media picker for a CKEditor field on a CMS page. Configure one backend directory, restrict to jpg,jpeg,png,gif,pdf, put the connector route behind auth + an admin gate, and confirm the editor can insert an image it just uploaded. That end-to-end loop exercises config, auth, storage, and the frontend integration in one afternoon.

Implementation Patterns

Treat the config file as your integration layer, not your application config. Keep config/ckfinder.php close to the package default and override via env vars where possible (CKFINDER_BASE_DIR, CKFINDER_BASE_URL). This makes the "one service provider, one config file" exit plan real — if you fork or replace the wrapper, the config shape survives.

Guard the connector with middleware, not just the auth callback. The package exposes a Laravel route; wrap it in your own middleware group rather than relying on a closure inside the config:

Route::middleware(['web', 'auth', 'can:manage-media'])
    ->get('/ckfinder/connector', [ConnectorController::class, 'handle'])
    ->name('ckfinder.connector');

If the package auto-registers the route, either disable that and re-register your own, or verify in route:list -v that the expected middleware is actually attached. Do not assume — read it.

Drive ACLs from Laravel auth. CKFinder's ACL callbacks are the right place to encode "editor can upload, viewer is read-only, admin can delete":

'acl' => function () {
    $user = Auth::user();
    return [
        'folder' => ['view' => true, 'create' => $user->can('upload-media')],
        'file'   => ['view' => true, 'upload' => $user->can('upload-media'), 'delete' => $user->can('delete-media')],
    ];
},

Keep this in a dedicated class (App\CKFinder\AclResolver) so you can unit-test it without booting CKFinder.

Isolate behind an adapter and a feature flag. Do not let CKFinder URLs or config leak into Blade templates, models, or services. One component (<x-media-picker>) or one helper (media_browser_url()) is the seam. Put it behind a config flag so a failed spike or a license lapse means flipping a boolean, not refactoring.

Map storage to a dedicated disk, never to public/. If the package supports filesystem disks, point it at something like media (S3 or a private local disk) and serve through a controller or signed URLs. If it only supports baseDir/baseUrl, set baseDir to storage/app/media and write a one-route proxy — do not let CKFinder write into public/uploads where every file is world-readable and executable.

Per-environment separation. Local: local disk, no CDN, thumbnails generated on demand. Staging/production: shared object storage so multiple app servers see the same files. Thumbnail generation on local disk behind a load balancer will produce broken images — plan for shared storage or a generation step at upload time.

Testing pattern. Write an integration test that hits the connector route with (a) no session → expect 401/403, (b) non-admin → 403, (c) admin → 200, (d) admin uploading a .php file → rejected. That test suite is more valuable than the wrapper itself, because it is what protects you if you later swap the wrapper for direct CKFinder integration.

Gotchas and Tips

Adoption is near-zero — assume unsupported code. Zero stars, zero dependents, zero score. There is no issue triage, no CVE feed, no Laravel-version tracking. Pin, vendor, and assign an owner. If it becomes load-bearing, budget for a fork — the wrapper is small enough that forking is realistic.

CKFinder is commercial. The package is free; the thing it connects to is not. Confirm license terms, seat count, and redistribution/deployment rights before the spike turns into a shipped feature. Also confirm which CKFinder 3 major version the wrapper targets — mismatched connector versions fail in confusing ways (PHP fatal errors inside the connector, not Laravel exceptions).

Route and middleware surprises. Auto-registered routes may not carry web, auth, or CSRF protection. Verify with php artisan route:list -v. If the connector is POST-upload and CSRF middleware is missing, that is an auth bypass risk; if CSRF is applied and the CKFinder JS client does not send a token, uploads 419 — the classic "uploads worked locally, fail in production" bug. Check both directions.

Upload hardening is yours. The wrapper delegates to CKFinder, and CKFinder's allowed-extension config is a first line, not a guarantee. Enforce MIME sniffing, extension allowlist, max size, and path containment yourself. Specifically test:

• ../../ in filenames and folder paths
• .php, .phtml, .htaccess, .svg with script payloads
• Double extensions (image.jpg.php)
• Uploads landing in a web-served directory

Public vs. private disk is a product decision, not a config detail. If files are on a public disk, "permissions" only control who can upload, not who can read. If they must be private, CKFinder's direct-URL model breaks and you need signed URLs or a proxy route.

Session expiry during long uploads. Large file uploads over a session that expires mid-request produce silent failures and orphaned partial files. Set session lifetime and post_max_size/upload_max_filesize/max_execution_time explicitly, and test a multi-minute upload.

Config caching and deployment drift. After php artisan config:cache, edits to config/ckfinder.php are invisible until recache. If paths are hardcoded rather than env-driven, staging and production will diverge silently. Diff the published config against the package default on upgrade.

Thumbnails and object storage. Thumbnail generation writes to local scratch; on S3 it may not propagate, and on multi-server local disk it produces intermittent 404s. Watch memory and disk space in the thumbnail pipeline too.

Orphaned files. Deletes can fail (permission, S3 eventual consistency, mid-request error) leaving files that no database row references. Write a periodic reconciliation job even if it only logs.

Debugging approach. When something breaks, bisect: does CKFinder work outside Laravel (raw connector)? Does the route resolve with auth stripped? Does the config differ from default? Most failures are auth/middleware, missing connector files, or a stale config cache — not the Laravel wrapper.

Extension points are limited by design. The config callbacks (auth, ACL) are the intended seams; anything else means editing src/ or forking. Decide up front whether you are comfortable owning those edits — if not, plan to wire CKFinder's official connector directly behind Laravel middleware instead.