Getting Started

Minimal Setup in Laravel

Install via Composer:
```
composer require barryvdh/laravel-elfinder
```
This package provides a Laravel-specific wrapper around studio-42/elfinder.

Publish Configuration:

php artisan vendor:publish --provider="Barryvdh\Elfinder\ElfinderServiceProvider"

This generates a config file at config/elfinder.php.

Configure Storage: Edit config/elfinder.php to define your storage paths, permissions, and allowed file types. Example:

'roots' => [
    [
        'driver' => 'local',
        'path'   => storage_path('app/public'),
        'URL'    => '/storage',
    ],
],

Add Routes: In routes/web.php, include the default routes:

Route::group(['middleware' => ['web']], function () {
    \Barryvdh\Elfinder\Elfinder::routes();
});

First Usage: Add a button or link to trigger the file manager in your Blade template:

<button id="elfinder-btn">Open File Manager</button>
<script>
    $('#elfinder-btn').elfinder({
        url: '/elfinder' // Default route
    });
</script>

Implementation Patterns

Common Workflows

Integrating with CKEditor/TinyMCE: Use the elfinder plugin for your editor. Example for CKEditor:

CKEDITOR.replace('editor', {
    filebrowserBrowseUrl: '/elfinder/ckeditor',
    filebrowserImageBrowseUrl: '/elfinder/ckeditor?type=image',
    filebrowserUploadUrl: '/elfinder/ckeditor?type=upload',
});

Customizing File Types: Extend allowed file types in config/elfinder.php:

'allowedMimeTypes' => [
    'image/jpeg', 'image/png', 'application/pdf', 'text/plain',
    'application/vnd.ms-excel', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
],

Multi-Root Configuration: Define multiple storage roots (e.g., local + S3):

'roots' => [
    ['driver' => 'local', 'path' => storage_path('app/public')],
    [
        'driver' => 's3',
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'bucket' => env('AWS_BUCKET'),
        'path'   => 'uploads',
    ],
],

Event Handling: Listen to file operations via Laravel events (e.g., Elfinder.Uploaded):

// In EventServiceProvider
protected $listen = [
    \Barryvdh\Elfinder\Events\Uploaded::class => [
        \App\Listeners\HandleUpload::class,
    ],
];

Dynamic Configuration: Override settings per request using middleware:

public function handle($request, Closure $next) {
    $request->attributes->add(['elfinder' => [
        'allowedMimeTypes' => ['image/jpeg', 'image/png'],
    ]]);
    return $next($request);
}

Integration Tips

Asset Optimization: Use Laravel Mix to bundle elFinder JS/CSS with your app:

// webpack.mix.js
mix.js('resources/js/app.js', 'public/js')
   .copy('vendor/studio-42/elFinder', 'public/vendor/elFinder');

Authentication: Secure routes with middleware:

Route::group(['middleware' => ['auth']], function () {
    \Barryvdh\Elfinder\Elfinder::routes();
});

Thumbnails: Ensure GD/Imagick is installed for image previews. Configure in config/elfinder.php:

'thumbnail' => [
    'mime' => ['image/jpeg', 'image/png', 'image/gif'],
    'path' => storage_path('app/thumbs'),
],

Custom Drivers: Extend Barryvdh\Elfinder\Driver\Local for custom logic (e.g., virtual paths).

Gotchas and Tips

Pitfalls

CSRF Protection: Ensure CSRF tokens are enabled in config/elfinder.php:
```
'csrf' => true,
```
If using Laravel's default CSRF middleware, conflicts may arise. Exclude /elfinder from CSRF checks if needed.
File Permissions: Set correct permissions for storage paths (e.g., chmod -R 775 storage/app/public).
Large File Uploads: Configure PHP settings (upload_max_filesize, post_max_size) and config/elfinder.php:
```
'uploadMaxSize' => 100 * 1024 * 1024, // 100MB
```
Path Encoding: Windows servers may struggle with non-ASCII paths. Use UTF-8 normalization:
```
'normalizer' => true,
```

CORS Issues: For AJAX requests, ensure CORS headers are set:

// In AppServiceProvider
Header::set('Access-Control-Allow-Origin', '*');

Debugging

Connector Errors: Check storage/logs/laravel.log for PHP errors. Enable debug mode in config/elfinder.php:
```
 'debug' => true,
```
JavaScript Errors: Inspect browser console for client-side issues. Verify jQuery/jQuery UI versions (1.8+/1.9+).

Volume Drivers: Test custom drivers in isolation:

// In a route
\Barryvdh\Elfinder\Elfinder::open('custom-driver');

Extension Points

Custom Commands: Extend the connector by adding commands in app/Providers/ElfinderServiceProvider.php:

public function boot() {
    \Barryvdh\Elfinder\Elfinder::commands([
        new \App\Commands\CustomCommand(),
    ]);
}

Themes: Override default CSS/JS by publishing assets:
```
php artisan vendor:publish --tag=elfinder-assets
```
Plugins: Use built-in plugins (e.g., AutoRotate, Watermark) by enabling in config:
```
'plugins' => ['AutoRotate', 'Watermark'],
```
Localization: Add language files to resources/lang/vendor/elfinder and update config/elfinder.php:
```
'lang' => 'es', // Spanish
```

Laravel-Specific Quirks

Queue Jobs: File operations (e.g., uploads) may block requests. Offload to queues:
```
event(new \Barryvdh\Elfinder\Events\Uploaded($file));
```
Storage Links: For public disk, create a symlink:
```
php artisan storage:link
```

Testing: Use ElfinderTestCase for unit tests:

use Barryvdh\Elfinder\Tests\ElfinderTestCase;

Elfinder Laravel Package