Getting Started

Minimal Setup

Install the Bundle
```
composer require helios-ag/fm-elfinder-bundle
```
Ensure helios-ag/fm-elfinder-bundle is listed in config/bundles.php.

Configure the Bundle Add the bundle to your config/packages/fm_elfinder.yaml (create if missing):

fm_elfinder:
    instances:
        default:
            connector: 'local' # or 'aws_s3' for S3 support
            root: '%kernel.project_dir%/public/uploads' # Local root path
            ACL:
                # Define ACL rules for S3 (if using aws_s3 connector)
                rules:
                    - { role: 'ROLE_ADMIN', permissions: ['read', 'write', 'delete'] }
                    - { role: 'ROLE_USER', permissions: ['read'] }

Enable the Connector For local storage, ensure the root directory exists and is writable. For AWS S3, configure AWS credentials in config/packages/fm_elfinder.yaml:

fm_elfinder:
    instances:
        default:
            connector: 'aws_s3'
            root: 'my-s3-bucket-name'
            ACL:
                rules: [...]
            aws_s3:
                key: '%env(AWS_ACCESS_KEY_ID)%'
                secret: '%env(AWS_SECRET_ACCESS_KEY)%'
                bucket: 'my-s3-bucket-name'
                region: 'us-east-1'

Integrate with a Twig Template Add the ElFinder JS/CSS and initialize it in your template:

{{ fm_elfinder('default')|raw }}
<script>
    $(document).ready(function() {
        $('#elfinder').elfinder({
            url: '{{ path('fm_elfinder_connector') }}',
            options: {
                // Custom options (e.g., language, theme)
            }
        });
    });
</script>

Route the Connector Ensure the connector route is defined in config/routes.yaml:

fm_elfinder_connector:
    path:     /elfinder/connector
    defaults: { _controller: 'FMElfinderBundle:Elfinder:connector' }
    methods:  [GET, POST]

First Use Case: Local File Uploads

Create a Form Use the ElFinder dialog in a TinyMCE or CKEditor field for file uploads:
```
{{ form_row(form.content, {'attr': {'class': 'elfinder-upload'}}) }}
```
Ensure the form includes the ElFinder JS initialization (as above).
Handle Uploads The bundle automatically processes uploads to the configured root directory. Verify permissions in var/log/dev.log for errors.

Implementation Patterns

Workflow: File Management with ACLs

Define Roles and Permissions Extend ACL rules in config/packages/fm_elfinder.yaml:

fm_elfinder:
    instances:
        default:
            ACL:
                rules:
                    - { role: 'ROLE_EDITOR', permissions: ['read', 'write'] }
                    - { role: 'ROLE_MODERATOR', permissions: ['read', 'delete'] }

Dynamic ACL Assignment Override ACL logic in a custom service (e.g., app/config/services.yaml):

services:
    App\Service\CustomElFinderACL:
        tags: ['fm_elfinder.acl_provider']

Implement FM\ElfinderBundle\ACL\ACLProviderInterface:

class CustomElFinderACL implements ACLProviderInterface {
    public function getRules(User $user) {
        if ($user->hasRole('ROLE_SUPER_ADMIN')) {
            return ['read', 'write', 'delete', 'create'];
        }
        return ['read'];
    }
}

S3-Specific Patterns
- Presigned URLs: Generate temporary URLs for file access:
```
use FM\ElfinderBundle\Connector\AwsS3Connector;
$connector = new AwsS3Connector($config);
$url = $connector->getPresignedUrl('file.jpg', '+1 hour');
```
- Lifecycle Policies: Configure S3 lifecycle rules via AWS Console to auto-archive old files.

Integration Tips

With TinyMCE/CKEditor Use the fm_tinymce or fos_ckeditor bundles to embed ElFinder as a file browser:

# config/packages/fm_tinymce.yaml
fm_tinymce:
    editor_selector: 'mce-editor'
    plugins: ['filemanager']
    filemanager:
        connector: '/elfinder/connector'

Custom Thumbnails Override the thumbnail command in config/packages/fm_elfinder.yaml:

fm_elfinder:
    instances:
        default:
            thumbnail:
                command: 'convert {source} -thumbnail 100x100 {destination}'

Event Listeners Listen to file events (e.g., uploads) via Symfony events:

// src/EventListener/ElFinderListener.php
namespace App\EventListener;

use FM\ElfinderBundle\Event\FileEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ElFinderListener implements EventSubscriberInterface {
    public static function getSubscribedEvents() {
        return [
            'fm_elfinder.file_uploaded' => 'onFileUploaded',
        ];
    }

    public function onFileUploaded(FileEvent $event) {
        // Log or process the uploaded file
        $file = $event->getFile();
        // ...
    }
}

Gotchas and Tips

Pitfalls

Permission Issues
- Local Storage: Ensure the root directory is writable by the web server user (e.g., chown -R www-data:www-data public/uploads).
- S3 ACLs: If using S3, verify IAM policies allow the configured role to perform s3:GetObject, s3:PutObject, etc.
```
aws iam list-attached-role-policies --role-name fm-elfinder-role
```

CORS Errors (S3) Configure CORS on the S3 bucket if accessing files directly:

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

ElFinder Version Mismatch The bundle may not support the latest ElFinder version. Check compatibility in the ElFinder GitHub. Downgrade ElFinder JS/CSS if needed:
```
<script src="https://cdn.jsdelivr.net/npm/elfinder@2.1.50/js/elfinder.min.js"></script>
```
ACL Caching ACL rules are cached. Clear the cache after changes:
```
php bin/console cache:clear
```

Debugging

Enable Debug Mode Set debug: true in config/packages/fm_elfinder.yaml:
```
fm_elfinder:
    debug: true
```
Check var/log/dev.log for connector errors.
Connector Errors Common errors and fixes:
- 403 Forbidden: Verify ACL rules and file permissions.
- 500 Internal Server Error: Check var/log/dev.log for PHP errors (e.g., missing AWS credentials).
- CORS Errors: Ensure S3 CORS policy is configured (see above).
Network Tab Insights Inspect the /elfinder/connector endpoint in browser dev tools to debug:
- Failed Commands: Look for cmd: "open" or cmd: "upload" errors.
- Response Codes: 200 (success), 403 (ACL denied), 500 (server error).

Extension Points

Custom Connectors Extend the connector logic by creating a custom class:

// src/Connector/CustomConnector.php
namespace App\Connector;

use FM\ElfinderBundle\Connector\AbstractConnector;

class CustomConnector extends AbstractConnector {
    protected function getFilesystem() {
        // Return a custom filesystem (e.g., Dropbox, FTP)
        return new \League\Flysystem\Filesystem(...);
    }
}

fm_elfinder:
    instances:
        custom:
            connector: 'custom'
            root: 'custom-root'

Fm Elfinder Bundle Laravel Package