Getting Started

Minimal Steps to First Use

Installation:

composer require livewire-filemanager/filemanager
php artisan vendor:publish --tag=livewire-filemanager-migrations
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
php artisan migrate

Basic Integration: Add the component and scripts to your blade template:
```
@filemanagerStyles
<x-livewire-filemanager />
@filemanagerScripts
```
First Use Case:
- Upload a file via drag-and-drop or the file picker.
- Navigate folders using the tree view.
- Copy the file URL from the context menu for immediate use in your application (e.g., <img src="copied-url">).

Where to Look First

Documentation: Start with the full documentation for API references and advanced configurations.
Component Props: Check the <x-livewire-filemanager /> component props (e.g., root-path, allowed-mime-types) in the source code.
API Endpoints: Explore /api/filemanager/v1/ for programmatic access (e.g., POST /folders to create a new folder).

Implementation Patterns

Core Workflows

1. File Uploads with Livewire

Pattern: Use the component in a Livewire form for seamless uploads.

public function mount() {
    $this->filemanagerRootPath = 'uploads';
}

Integration Tip: Bind the uploaded file path to a model attribute:

public function save() {
    $this->validate(['file_path' => 'required']);
    $this->model->update(['image_path' => $this->file_path]);
}

2. Folder-Specific Access

Pattern: Restrict filemanager access to specific folders per user/role.

// In your Livewire component
public function mount() {
    $this->rootPath = auth()->user()->folder_path; // e.g., 'users/{id}/documents'
}

Integration Tip: Use middleware to enforce folder permissions:

Route::middleware(['auth', 'can:access-filemanager'])->get('/filemanager', FilemanagerComponent::class);

3. API-Driven File Management

Pattern: Use the API for backend-to-backend operations (e.g., syncing files between services).

# Create a folder via API
curl -X POST -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"name":"reports", "path":"documents"}' \
     http://your-app.test/api/filemanager/v1/folders

Integration Tip: Cache API responses for performance:

$folder = Cache::remember("filemanager:folder:{$id}", now()->addHours(1), function() use ($id) {
    return \LivewireFilemanager\Filemanager\Http\Requests\FolderRequest::find($id);
});

4. Thumbnail Generation

Pattern: Offload thumbnail generation to a queue for async processing.

// In your FileController or Livewire component
public function handleUpload() {
    $file = $this->uploadFile();
    Thumbnail::dispatch($file)->delay(now()->addSeconds(10));
}

Integration Tip: Configure the queue connection in .env:
```
QUEUE_CONNECTION=database
```

5. Multi-Tenancy

Pattern: Scope folders by tenant ID.

public function mount() {
    $this->rootPath = "tenants/{$this->tenant->id}/uploads";
}

Integration Tip: Use a trait to dynamically set the root path:

use LivewireFilemanager\Filemanager\Traits\TenantAware;

class TenantFilemanager extends Filemanager {
    use TenantAware;
}

Advanced Patterns

Customizing the UI

Override the default views by publishing the package assets:

php artisan vendor:publish --tag=livewire-filemanager-views

Modify the resources/views/vendor/livewire-filemanager/ files to match your app’s design system (e.g., replace Tailwind classes with your CSS variables).

Extending Functionality

Add Custom Actions: Extend the context menu by publishing the JS assets and adding custom Alpine.js logic:

// resources/js/filemanager-extensions.js
document.addEventListener('livewire-filemanager-initialized', () => {
    Livewire.hook('filemanager.context-menu', (menu) => {
        menu.addItem('custom-action', 'Custom Action', () => {
            alert('Triggered!');
        });
    });
});

Integration Tip: Load the custom JS after the filemanager scripts:

@filemanagerScripts
<script src="{{ asset('js/filemanager-extensions.js') }}"></script>

Programmatic File Operations

Use the API or service classes to manipulate files without the UI:

use LivewireFilemanager\Filemanager\Facades\Filemanager;

// Upload a file programmatically
$file = Filemanager::upload('path/to/file.jpg', 'uploads/');

// Delete a file
Filemanager::delete($file->path);

Gotchas and Tips

Pitfalls

Queue Configuration for Thumbnails:
- Gotcha: Thumbnails are generated asynchronously via queues. If QUEUE_CONNECTION is not configured (e.g., set to sync), thumbnails will block the request.
- Fix: Set QUEUE_CONNECTION=database in .env and run the queue worker:
```
php artisan queue:work
```
- Tip: For production, use a dedicated queue worker (e.g., supervisor) to avoid blocking HTTP requests.
HTTPS Requirement for File URLs:
- Gotcha: The "Copy URL" feature requires HTTPS. If your app uses HTTP, the copied URL will be invalid.
- Fix: Ensure your domain is HTTPS-enabled or override the URL generation in the FileController:
```
public function show($path) {
    return response()->file(storage_path('app/' . $path));
    // Or use a custom URL generator:
    // return response()->file(url("https://your-app.test/storage/{$path}"));
}
```
Permission Denied Errors:
- Gotcha: If using ACL, ensure the media_model in spatie/medialibrary is set to LivewireFilemanager\Filemanager\Models\Media.
- Fix: Publish the config and update:
```
// config/medialibrary.php
'media_model' => \LivewireFilemanager\Filemanager\Models\Media::class,
```
- Tip: Use Laravel Gates/Policies for granular control:
```
Gate::define('delete-file', function ($user, $file) {
    return $user->id === $file->owner_id;
});
```
Tailwind CSS in Production:
- Gotcha: The @filemanagerStyles directive includes Tailwind’s Play CDN, which is not suitable for production.
- Fix: Configure Tailwind to include the package’s views:
```
// tailwind.config.js
module.exports = {
    content: [
        './resources/**/*.blade.php',
        './vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php',
    ],
};
```
- Tip: Use PurgeCSS to remove unused styles:
```
npm run production
```
Large File Uploads:
- Gotcha: By default, PHP’s upload_max_filesize and post_max_size may limit file uploads.
- Fix: Adjust these settings in php.ini or use chunked uploads:
```
// In your Livewire component
public function mount() {
    $this->maxFileSize = 10 * 1024 * 1024; // 10MB
}
```
- Tip: Use Laravel’s chunked-upload middleware for files > 100MB.

Debugging Tips

Log File Operations:

Enable Spatie Media Library’s event logging:

// In a service provider
\Spatie\MediaLibrary\MediaEvents::save(function ($model, $path) {
    \Log::info("File uploaded: {$path}", ['model' => $model]);
});

Check Queue Jobs:

Monitor thumbnail generation jobs:

php artisan queue:failed-table
php artisan queue:work --once

Verify Folder Structure:
- Ensure the `

Filemanager Laravel Package