Livewire Filemanager Documentation

Introduction
Requirements
Installation
Configuration
Architecture
API Reference
Access Control (ACL)
Internationalization
Security
Testing
Troubleshooting

Introduction

Livewire Filemanager is a comprehensive file management package for Laravel applications. Built with Livewire 3, it provides a modern, user-friendly interface for managing files and folders, complete with API endpoints for programmatic access.

Key Features

Drag & Drop Support: Intuitive file upload interface
Real-time Search: Find files and folders instantly
Multi-language Support: Available in 11 languages
Dark Mode: Built-in dark/light theme support
RESTful API: Complete API for programmatic access
ACL Support: Optional access control for multi-user environments
Thumbnail Generation: Automatic thumbnail creation for images
Laravel Integration: Seamless integration with Laravel ecosystem

Requirements

PHP: 8.2.0 or greater
Laravel: 10.x, 11.x, or 12.x
Livewire: 3.5.4 or greater
Dependencies:
- livewire/livewire
- spatie/laravel-medialibrary

Installation

Step 1: Install via Composer

composer require livewire-filemanager/filemanager

Step 2: Publish Migrations

# Publish filemanager migrations
php artisan vendor:publish --tag=livewire-filemanager-migrations

# Publish Spatie Media Library migrations (if not already done)
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"

Step 3: Run Migrations

php artisan migrate

This creates:

folders table: Stores folder hierarchy
media table: Stores file information (via Spatie Media Library)

Step 4: Basic Implementation

Add the filemanager component to your Blade template:

<!DOCTYPE html>
<html>
<head>
    @filemanagerStyles
</head>
<body>
    <x-livewire-filemanager />

    @filemanagerScripts
</body>
</html>

Step 5: Configure Tailwind CSS

For production environments, include the package views in your Tailwind configuration:

Tailwind v4 (app.css):

@source '../../vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php';

Tailwind v3 (tailwind.config.js):

module.exports = {
    content: [
        './resources/**/*.blade.php',
        './vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php',
    ],
}

Step 6: Optional - Direct File Access

To enable direct file access via URL:

// routes/web.php
use LivewireFilemanager\Filemanager\Http\Controllers\Files\FileController;

Route::get('{path}', [FileController::class, 'show'])
    ->where('path', '.*')
    ->name('assets.show');

Configuration

Publishing Configuration

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

Configuration Options

The config/livewire-filemanager.php file includes:

return [
    // Access Control
    'acl_enabled' => false,

    // API Configuration
    'api' => [
        'enabled' => true,
        'prefix' => 'filemanager/v1',
        'middleware' => ['api', 'auth:sanctum'],
        'rate_limit' => '100,1',
        'max_file_size' => 10240,
        'allowed_extensions' => ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'doc', 'docx', 'txt', 'zip'],
        'chunk_size' => 1048576,
    ],

    // Callbacks
    'callbacks' => [
        'before_upload' => null,
        'after_upload' => null,
        'before_delete' => null,
        'after_delete' => null,
    ],
];

Architecture

Directory Structure

filemanager/
├── config/
│   └── livewire-filemanager.stub      # Configuration template
├── database/
│   └── migrations/                     # Database migrations
├── resources/
│   ├── lang/                          # Language files (11 languages)
│   └── views/                         # Blade templates
│       ├── components/                # UI components
│       ├── livewire/                  # Livewire component views
│       └── partials/                  # Shared partials
├── src/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/                   # API controllers
│   │   │   └── Files/                 # File access controller
│   │   └── Middleware/                # Custom middleware
│   ├── Livewire/                      # Livewire components
│   ├── Models/                        # Eloquent models
│   ├── Policies/                      # Authorization policies
│   ├── Traits/                        # Reusable traits
│   └── FilemanagerServiceProvider.php # Service provider
└── tests/                             # Test suite

Database Schema

Folders Table

- id (primary key)
- name (string)
- parent_id (nullable, foreign key)
- user_id (nullable, for ACL)
- created_at
- updated_at

Media Table (Spatie Media Library)

- id (primary key)
- model_type
- model_id
- collection_name
- name
- file_name
- mime_type
- disk
- size
- custom_properties
- generated_conversions
- responsive_images
- manipulations
- created_at
- updated_at

API Reference

Authentication

The API uses Laravel Sanctum for authentication. Include the bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Base URL

https://your-domain.com/api/filemanager/v1

Endpoints

Folders

List Folders

GET /folders

Response:

{
    "data": [
        {
            "id": 1,
            "name": "Documents",
            "parent_id": null,
            "created_at": "2024-01-01T00:00:00Z",
            "updated_at": "2024-01-01T00:00:00Z"
        }
    ]
}

Create Folder

POST /folders
Content-Type: application/json

{
    "name": "New Folder",
    "parent_id": 1
}

Update Folder

PUT /folders/{id}
Content-Type: application/json

{
    "name": "Renamed Folder"
}

Delete Folder

DELETE /folders/{id}

Files

List Files

GET /files

Parameters:

folder_id (optional): Filter files by folder
search (optional): Search files by name
page (optional): Page number for pagination
per_page (optional): Items per page (default: 20)

Upload File

POST /files
Content-Type: multipart/form-data

{
    "file": <binary>,
    "folder_id": 1
}

Upload to Specific Folder

POST /folders/{folder}/upload
Content-Type: multipart/form-data

{
    "file": <binary>
}

Bulk Upload

POST /files/bulk
Content-Type: multipart/form-data

{
    "files[]": <binary>,
    "folder_id": 1
}

Update File

PUT /files/{id}
Content-Type: application/json

{
    "name": "renamed-file.pdf"
}

Delete File

DELETE /files/{id}

Error Responses

{
    "message": "Validation error",
    "errors": {
        "name": ["The name field is required."]
    }
}

Status Codes:

200: Success
201: Created
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
422: Validation Error
429: Too Many Requests

Access Control (ACL)

Enabling ACL

Publish configuration:

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

Enable ACL in config:

'acl_enabled' => true,

How ACL Works

When ACL is enabled:

Files and folders are scoped to the creating user
Users can only see and manage their own files
The user_id field is automatically populated
Global scopes ensure data isolation

Internationalization

Supported Languages

Arabic (ar)
English (en)
Spanish (es)
Persian (fa)
French (fr)
Hebrew (he)
Italian (it)
Portuguese - Brazil (pt_BR)
Portuguese - Portugal (pt_PT)
Romanian (ro)
Turkish (tr)

Setting Language

The package automatically uses Laravel's locale:

// Set application locale
App::setLocale('fr');

Adding Translations

Create language file in resources/lang/{locale}/filemanager.php
Override specific translations:

// resources/lang/es/filemanager.php
return [
    'upload' => 'Subir archivo',
    'create_folder' => 'Crear carpeta',
    // ... other translations
];

Customization

Custom Views

Override package views:

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

Then modify views in resources/views/vendor/livewire-filemanager/.

Styling

The package uses TailwindCSS classes. Customize by:

Using CSS variables:

:root {
    --filemanager-primary: #3B82F6;
    --filemanager-secondary: #6B7280;
}

Overriding Tailwind classes in your CSS:

.livewire-filemanager-container {
    @apply bg-gray-50 dark:bg-gray-900;
}

Security

File Upload Validation

Both the API endpoints and Livewire component validate file uploads against the configured allowed extensions and maximum file size.

Configuration:

// config/livewire-filemanager.php
'api' => [
    'max_file_size' => 10240, // KB
    'allowed_extensions' => ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'doc', 'docx', 'txt', 'zip'],
],

Blocked by default:

PHP files (.php, .phtml, .php5, etc.)
Executable files (.exe, .sh, .bat, etc.)
Server-side scripts

Important Considerations

Warning: While this package validates file types, you are still responsible for:

Implementing proper access control (see ACL section)

Scanning uploads for malware in sensitive environments

Configuring your web server to prevent PHP execution in storage directories

Web Server Hardening

Prevent PHP execution in storage directory:

Apache (.htaccess in storage/app/public/):

<FilesMatch "\.php$">
    Deny from all
</FilesMatch>

Nginx:

location ~* /storage/.*\.php$ {
    deny all;
}

Best Practices

File Validation
- Configure allowed extensions to only what your application needs
- Set appropriate maximum file sizes
- Both API and Livewire component enforce the same validation rules
Access Control
- Enable ACL for multi-user environments
- Implement custom policies for sensitive files
- Use middleware for route protection
Storage Security
- Consider storing files on a private disk
- Use signed URLs for temporary access
- Implement download authorization
- Configure web server to prevent script execution in storage
API Security
- Use Sanctum authentication
- Implement rate limiting
- Validate all inputs

Testing

Running Tests

# Run all tests
composer test

Troubleshooting

Common Issues

Thumbnails Not Generating

Problem: Image thumbnails are not appearing.

Solution: Ensure queue workers are running:

php artisan queue:work

Or disable queued processing:

QUEUE_CONNECTION=sync

Tailwind Classes Not Applied

Problem: UI appears broken or unstyled.

Solution: Ensure package views are included in Tailwind config and rebuild:

npm run build

Files Not Uploading

Problem: File uploads fail silently.

Solution: Check:

PHP upload limits in php.ini:

upload_max_filesize = 20M
post_max_size = 25M

Laravel validation rules

Storage permissions:

chmod -R 775 storage
chown -R www-data:www-data storage

ACL Not Working

Problem: Users can see all files despite ACL being enabled.

Solution:

Clear cache: php artisan cache:clear
Verify Media model is correct in config
Check user_id is being set on uploads

API Returns 401

Problem: API requests return unauthorized.