Getting Started

This is a Symfony bundle, not a Laravel package. A Laravel developer can assess it for a Symfony project, but do not expect composer require plus a service provider in Laravel. In Laravel, you would use standalone elFinder or build a small connector around its PHP backend.

For a Symfony app, the minimal path is:

Allow Symfony contrib recipes and install:

composer config extra.symfony.allow-contrib true
composer require helios-ag/fm-elfinder-bundle

Publish elFinder assets in the correct order:

bin/console elfinder:install
bin/console assets:install public

Create and permission the upload directory:

mkdir -p public/uploads

Import routing:

# config/routes.yaml
elfinder:
    resource: "@FMElfinderBundle/Resources/config/routing.yaml"

Protect both the UI and connector routes:

# config/packages/security.yaml
security:
    access_control:
        - { path: ^/efconnect, roles: ROLE_USER }
        - { path: ^/elfinder, roles: ROLE_USER }

Add a basic instance:

# config/packages/fm_elfinder.yaml
fm_elfinder:
    assets_path: /
    instances:
        default:
            locale: '%locale%'
            editor: ckeditor
            connector:
                roots:
                    uploads:
                        driver: LocalFileSystem
                        path: '%kernel.project_dir%/public/uploads'
                        url: /uploads
                        upload_allow: ['image/png', 'image/jpg', 'image/jpeg']
                        upload_deny: ['all']
                        upload_max_size: 2M

The first practical use case is a CKEditor/TinyMCE image button that opens elFinder, lets an editor browse /uploads, and uploads new images there. Verify /elfinder renders the file manager and /efconnect responds as the connector. Look first at the README, then docs/ckeditor-integration.md or docs/tinymce-integration.md, followed by docs/advanced-configuration.md, docs/events-listeners-subscribers.md, and docs/configuration-dump.md.

Implementation Patterns

Use one instance per editor or context. Instances let you expose different roots, locales, upload rules, and templates. For example, a default instance for CKEditor and a separate cms instance with a more restricted root.

Treat roots as virtual volumes. Each root maps a filesystem path, public URL, driver, alias, upload rules, and attributes. Keep read-only roots for shared assets and writable roots for user uploads:

roots:
    shared:
        driver: LocalFileSystem
        path: '%kernel.project_dir%/public/shared'
        url: /shared
        attributes:
            - { pattern: '/(.*?)/', read: true, write: false, locked: true }

    uploads:
        driver: LocalFileSystem
        path: '%kernel.project_dir%/public/uploads'
        url: /uploads
        upload_allow: ['image/png', 'image/jpeg']
        upload_deny: ['all']
        upload_max_size: 5M

Wire the editor through the editor option. Use ckeditor, tinymce5 for TinyMCE 5–8, fm_tinymce for TinyMCE 4, form for form types, simple for standalone use, or custom with editor_template. The editor name is the main integration switch, so match it to the frontend package you actually use.

Use per-user home folders for multi-tenant uploads. With LocalFileSystem, access /elfinder/{instance}/{homeFolder} or /efconnect/{instance}/{homeFolder} to remap the root to a subfolder such as /uploads/bob. This is a simple way to isolate user files without creating one instance per user. It requires the instance name in the URL and correct folder permissions.

Use the form type when files are part of an entity. The bundle’s elFinder form type fits Symfony forms and EasyAdmin 2/3/4 integrations. This is the day-to-day pattern for “choose an image/file” fields rather than direct editor integration.

Use events and subscribers for audit and dynamic behavior. The bundle documents events and sub-requests. Use these for logging uploads/downloads, applying dynamic root restrictions, or reacting to connector activity instead of forking the bundle.

Use custom providers/loaders and drivers for non-local storage. docs/advanced-configuration.md covers custom configuration providers, custom loaders, plugins, service-as-volume-driver, and Flysystem. For S3/FTP or other backends, prefer the documented driver/config extension points over hacking LocalFileSystem.

Use CORS only when the editor and connector are on different origins. The bundle has CORS support, but do not enable it globally without need. Keep connector routes behind authentication first.

Keep asset publishing in Composer auto-scripts. The README’s recommended order is cache:clear, elfinder:install, then assets:install %PUBLIC_DIR%. This avoids deploying an app where the connector works but the frontend assets are missing.

Gotchas and Tips

Install order matters. Run elfinder:install before assets:install. If assets are missing, check public/bundles/fmelfinder, the assets_path setting, and whether assets:install ran after elfinder:install.

path and url are not the same thing. path is a filesystem path; url is the public URL prefix used to display files. Set both explicitly for local roots. A mismatch produces a working file manager with broken previews or download links. For non-vhost setups, use path_prefix and review relative_path.

Permissions are a common failure point. The PHP user and web server need read/write access to the upload directory. Check ownership, directory permissions, and any open_basedir or container volume restrictions.

Upload limits are enforced twice. upload_max_size is the elFinder/bundle limit, but PHP’s upload_max_filesize and post_max_size also apply. If uploads fail silently, inspect both Symfony/PHP logs and the connector debug output.

Do not accidentally allow everything. upload_deny: ['all'] with an explicit upload_allow list is a safer default. Review visible_mime_types, show_hidden, and root attributes before exposing the connector to non-admin users.

Home-folder routing has constraints. The per-user home-folder feature is only available with LocalFileSystem. The instance name must be present in the URL. The multi-home-folder variant uses where_is_multi, multi_home_folder, and a folder_separator other than /; misconfiguration here is easy to miss because the UI may still load but point at the wrong root.

Editor names are version-sensitive. tinymce5 covers TinyMCE 5–8, while fm_tinymce is for TinyMCE 4. Using the wrong value often results in a rendered page with a non-functional editor integration rather than a hard exception.

Secure both /elfinder and /efconnect. The UI route alone is not enough; the connector is the endpoint that actually reads and writes files. Apply access_control, and consider additional voter/event checks for per-root or per-user access.

Debug with Symfony’s normal tools. Use bin/console debug:router to confirm route names and paths, bin/console debug:config fm_elfinder to inspect resolved configuration, and connector debug: true temporarily when diagnosing backend behavior. Remove debug mode before production.

Version compatibility deserves a smoke test. The changelog shows asset/path fixes for elFinder component compatibility. Pin versions and test the editor integration, asset URLs, and connector after upgrades rather than assuming a minor release is transparent.

This is a niche Symfony integration. The docs, changelog, and release history are useful, but the package is not Laravel-native and has a small ecosystem. Budget time for reading the advanced docs and testing your specific driver/editor combination. For a Laravel application, prefer standalone elFinder or a custom adapter; for Symfony, this bundle is a reasonable shortcut when you need editor-friendly file management quickly.

Fm Elfinder Bundle Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips