Getting Started

Minimal Setup

Installation:

composer require unisharp/laravel-filemanager
php artisan vendor:publish --tag=lfm_config
php artisan vendor:publish --tag=lfm_view
php artisan vendor:publish --tag=lfm_lang
php artisan migrate

Run migrations to create necessary tables for file tracking.

Basic Route Configuration (in routes/web.php):

Route::group(['prefix' => 'lfm', 'middleware' => ['web', 'auth']], function () {
    \UniSharp\LaravelFilemanager\Lfm::routes();
});

First Use Case: CKEditor Integration Add this to your CKEditor initialization:

CKEDITOR.replace('editor', {
    filebrowserImageBrowseUrl: '/lfm?type=Images',
    filebrowserBrowseUrl: '/lfm?type=Files'
});

Implementation Patterns

1. WYSIWYG Editor Integration

CKEditor: Use filebrowserImageBrowseUrl and filebrowserBrowseUrl with ?type=Images or ?type=Files.
TinyMCE: Configure file_picker_callback or use file_browser_callback with custom routes.
Summernote: Use the filemanager plugin with the same route pattern.

2. Standalone Upload Button

Create a button linking to the filemanager:

<a href="/lfm?type=Files" class="btn btn-primary">Upload Files</a>

Or use the iframe mode:

<iframe src="/lfm?type=Images" width="100%" height="600px"></iframe>

3. Multi-User Workflows

Private Folders: Users automatically get a dedicated folder (e.g., /storage/app/public/photos/{user_id}/).
Shared Folders: Configure shared_folder_name in lfm.php (default: shares). All users can access files here.

4. Cloud Storage Integration

Leverage Laravel’s filesystem (e.g., S3, FTP) by setting the disk config in lfm.php:

'disk' => 's3',

5. Custom File Categories

Extend folder_categories in lfm.php for specialized folders (e.g., documents, videos):

'folder_categories' => [
    'documents' => [
        'folder_name' => 'docs',
        'valid_mime' => ['application/pdf', 'application/msword'],
    ],
],

6. Event-Driven Customization

Listen to filemanager events (e.g., fileUploaded, fileDeleted) in EventServiceProvider:

protected $listen = [
    \UniSharp\LaravelFilemanager\Events\FileUploaded::class => [
        'App\Listeners\LogUploadedFile',
    ],
];

Gotchas and Tips

Common Pitfalls

Authentication Middleware:
- Issue: Filemanager routes may expose upload endpoints without auth.
- Fix: Always wrap routes in auth middleware (e.g., Route::group(['middleware' => ['auth']], ...)).

File Permissions:

Issue: Uploads fail due to storage permissions.

Fix: Ensure storage/app/public is writable:

chmod -R 775 storage/app/public
chown -R www-data:www-data storage/app/public  # Adjust user/group as needed

Thumbnail Generation:
- Issue: Thumbnails not created for certain image types.
- Fix: Add missing MIME types to raster_mimetypes in lfm.php or disable with should_create_thumbnails: false.
Route Conflicts:
- Issue: Custom routes clash with package defaults.
- Fix: Disable use_package_routes in lfm.php and manually define routes.
Large File Uploads:
- Issue: post_max_size or upload_max_filesize limits in php.ini block uploads.
- Fix: Temporarily override in lfm.php (note: caveats apply):
```
'php_ini_overrides' => [
    'memory_limit' => '512M',
],
```

Debugging Tips

Check Logs: Use php artisan lfm:clear-cache to reset cached views/configs.
Validate MIME Types: Test uploads with tools like MIME Sniffer to debug rejected files.

Inspect Events: Add dd() in event listeners to debug file operations:

public function handle(FileUploaded $event) {
    dd($event->file); // Inspect uploaded file data
}

Extension Points

Custom Handlers:
- Publish and extend ConfigHandler for dynamic folder naming:
```
php artisan publish --tag=lfm_handler
```
- Override userField() to use custom user identifiers (e.g., email):
```
public function userField() {
    return auth()->user()->email;
}
```
Custom Validation:
- Extend FileValidator by publishing the service provider:
```
php artisan publish --tag=lfm_provider
```
- Add logic in validate() method to enforce custom rules (e.g., file naming conventions).

API Integration:

Use the Lfm facade to trigger actions programmatically:

use UniSharp\LaravelFilemanager\Facades\Lfm;
$files = Lfm::getFiles('Images', ['perPage' => 100]);

Localization:
- Override translations by publishing language files:
```
php artisan publish --tag=lfm_lang
```
- Add new locales by copying en to resources/lang/vendor/laravel-filemanager/{locale}.

Performance Optimizations

Disable Thumbnails: Set should_create_thumbnails: false if not needed.
Batch Processing: Use paginator.perPage to limit API response sizes (default: 30).
Lazy Loading: Load large files asynchronously in the frontend (e.g., using AJAX for file previews).

Security Considerations

Restrict File Types: Whitelist only necessary MIME types in valid_mime to prevent malicious uploads.
Size Limits: Enforce should_validate_size: true and set max_size to mitigate DoS risks.
Private Folders: Use allow_private_folder: true to isolate user uploads and prevent unauthorized access.


```markdown
### **Pro Tips for Daily Workflows**
1. **Quick Testing**:
   Use the standalone iframe (`/lfm?type=Images`) for ad-hoc uploads during development.

2. **Bulk Operations**:
   Select multiple files in the grid/list view and use the bulk actions (delete, download) for efficiency.

3. **Image Editing**:
   Leverage the built-in crop/resize tools for thumbnails or social media previews without external tools.

4. **Multi-Environment Configs**:
   Override `lfm.php` per environment (e.g., `lfm-local.php`, `lfm-production.php`) for disk/storage differences.

5. **Backup Integration**:
   Use the `fileDeleted` event to log deleted files for backup purposes:
   ```php
   public function handle(FileDeleted $event) {
       \Log::info('Deleted file: ' . $event->file->path);
   }

Custom Metadata: Extend the file table by publishing migrations:
```
php artisan vendor:publish --tag=lfm_migrations
```
Add columns like alt_text or metadata to files table for SEO or analytics.

Laravel Filemanager Laravel Package