README

A modern, elegant file manager package for Laravel applications built with FluxUI and Livewire. Provides a complete file management solution with drag-and-drop uploads, folder navigation, file selection components, and comprehensive file operations.

Features

🗂️ File Browser: Navigate through folders with breadcrumb navigation
📤 File Upload: Drag-and-drop file uploads with progress indication
🎯 File Selection: Easy file picker component for forms
📁 Folder Management: Create, rename, and delete folders
🔄 File Operations: Rename and delete files
🎨 FluxUI Integration: Beautiful, responsive UI components
🌓 Dark Mode: Automatic light/dark mode compatibility
🏗️ Multi-tenancy: Built-in tenant isolation support
📱 Responsive: Mobile-friendly design
🔒 Validation: Comprehensive file type and size validation

Requirements

PHP 8.4 or higher
Laravel 11.x
Livewire Flux 2.2.3+
Livewire Flux Pro 2.2.3+

Installation

You can install the package via composer:

composer require idkwhoami/flux-files

Run the installation command to publish the necessary files:

php artisan flux-files:install

This command will:

Publish the configuration file
Publish the database migrations
Publish the models to your app
Publish language files

Run the migrations:

php artisan migrate

Configuration

The configuration file is published to config/flux-files.php. Here are the main configuration options:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Default Storage Disk
    |--------------------------------------------------------------------------
    |
    | The default disk to use for file storage.
    |
    */
    'disk' => env('FLUX_FILES_DISK', 'local'),

    /*
    |--------------------------------------------------------------------------
    | File Validation
    |--------------------------------------------------------------------------
    |
    | Configure file upload restrictions and validation rules.
    |
    */
    'validation' => [
        'max_file_size' => env('FLUX_FILES_MAX_SIZE', 10240), // KB
        'allowed_extensions' => [
            'images' => ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg'],
            'documents' => ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'],
            'archives' => ['zip', 'rar', '7z', 'tar', 'gz'],
            'audio' => ['mp3', 'wav', 'ogg', 'flac'],
            'video' => ['mp4', 'avi', 'mov', 'wmv', 'flv'],
        ],
        'mime_types' => [
            // Auto-generated based on extensions
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Eloquent Configuration
    |--------------------------------------------------------------------------
    |
    | Configure the ID type for models (bigint, uuid, ulid).
    |
    */
    'eloquent' => [
        'id_type' => env('FLUX_FILES_ID_TYPE', 'bigint'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Multi-tenancy
    |--------------------------------------------------------------------------
    |
    | Enable multi-tenant support for file isolation.
    |
    */
    'multi_tenant' => [
        'enabled' => env('FLUX_FILES_MULTI_TENANT', false),
        'tenant_model' => null, // Your tenant model class
        'tenant_key' => 'tenant_id',
    ],
];

Usage

File Browser Component

The file browser component provides a complete file management interface:

<livewire:flux-files.browser 
    :current-folder-id="null"
    view-mode="grid"
    :selectable="false" />

Properties:

current-folder-id: ID of the folder to display (null for root)
view-mode: Display mode ('grid' or 'table')
selectable: Whether files can be selected

Events:

file-selected: Fired when a file is selected
folder-changed: Fired when navigating to a different folder

File Selection Component

Use this component to add file selection to forms:

<livewire:flux-files.select 
    name="avatar"
    :selected-file-id="$user->avatar_id"
    placeholder="Select an image..."
    :required="true" />

Properties:

name: Form field name
selected-file-id: ID of the currently selected file
placeholder: Placeholder text
required: Whether selection is required

File Upload Component

For drag-and-drop file uploads:

<livewire:flux-files.upload 
    :target-folder-id="$folderId"
    :allowed-types="['images', 'documents']"
    :max-files="5" />

Properties:

target-folder-id: ID of the folder to upload to
allowed-types: Array of allowed file type categories
max-files: Maximum number of files to upload

Blade Components

The package provides numerous Blade components for custom implementations:

File Display Components

<x-flux-files:file-icon :file="$file" />
<x-flux-files:folder-icon :folder="$folder" />
<x-flux-files:file-item-grid :file="$file" />
<x-flux-files:file-item-table :file="$file" />
<x-flux-files:file-preview :file="$file" />
<x-flux-files:file-size :file="$file" />
<x-flux-files:file-date :file="$file" />

Navigation Components

<x-flux-files:breadcrumbs :current-folder="$folder" />
<x-flux-files:view-mode-toggle />
<x-flux-files:sort-controls />

Upload Components

<x-flux-files:drop-zone />
<x-flux-files:upload-progress :files="$files" />
<x-flux-files:file-upload-item :file="$file" />

Models

The package includes two main models:

File Model

use App\Models\File;

// Get file URL
$url = $file->getUrl();

// Get preview URL (for images)
$previewUrl = $file->getPreviewUrl();

// Check file type
$isImage = $file->isImage();
$isAudio = $file->isAudio();
$isVideo = $file->isVideo();

// Get human-readable size
$size = $file->getHumanReadableSize();

// Relationships
$folder = $file->folder;
$tenant = $file->tenant; // if multi-tenancy enabled

// Scopes
$files = File::byTenant($tenantId)->get();
$images = File::byMimeType('image')->get();
$folderFiles = File::inFolder($folderId)->get();

Folder Model

use App\Models\Folder;

// Get full folder path
$path = $folder->getFullPath();

// Check if folder is ancestor of another
$isAncestor = $folder->isAncestorOf($otherFolder);

// Get all descendants
$descendants = $folder->getDescendants();

// Create subfolder
$subfolder = $folder->createSubfolder('New Folder');

// Relationships
$files = $folder->files;
$children = $folder->children;
$parent = $folder->parent;

// Scopes
$rootFolders = Folder::roots()->get();
$tenantFolders = Folder::byTenant($tenantId)->get();

Services

FileStorageService

use Idkwhoami\FluxFiles\Services\FileStorageService;

$storage = app(FileStorageService::class);

// Store file
$file = $storage->store($uploadedFile, $folderId);

// Delete file
$storage->delete($file);

// Move file
$storage->move($file, $newFolderId);

// Copy file
$newFile = $storage->copy($file, $targetFolderId);

// Check if file exists
$exists = $storage->exists($file);

FileValidationService

use Idkwhoami\FluxFiles\Services\FileValidationService;

$validator = app(FileValidationService::class);

// Validate file
$isValid = $validator->validateFile($uploadedFile);

// Validate file type
$isValidType = $validator->validateFileType($uploadedFile, ['images']);

// Validate file size
$isValidSize = $validator->validateFileSize($uploadedFile);

// Get validation errors
$errors = $validator->getErrors();

Advanced Usage

Multi-tenancy

Enable multi-tenancy in your configuration:

'multi_tenant' => [
    'enabled' => true,
    'tenant_model' => App\Models\Tenant::class,
    'tenant_key' => 'tenant_id',
],

Then use the tenant scope in your queries:

// Get files for current tenant
$files = File::byTenant(auth()->user()->tenant_id)->get();

// Get folders for current tenant
$folders = Folder::byTenant(auth()->user()->tenant_id)->get();

Custom File Types

Add custom file type validation:

// In your service provider
use Idkwhoami\FluxFiles\Services\FileValidationService;

FileValidationService::addCustomType('custom', [
    'extensions' => ['custom', 'ext'],
    'mime_types' => ['application/custom'],
    'max_size' => 5120, // KB
]);

Events

Listen for file events:

use Idkwhoami\FluxFiles\Events\FileUploaded;
use Idkwhoami\FluxFiles\Events\FileDeleted;

// In your EventServiceProvider
protected $listen = [
    FileUploaded::class => [
        // Your listeners
    ],
    FileDeleted::class => [
        // Your listeners
    ],
];

Custom Views

Publish and customize the views:

php artisan vendor:publish --tag=flux-files-views

Views will be published to resources/views/vendor/flux-files/.

Commands

The package includes helpful Artisan commands:

Install Command

php artisan flux-files:install

Publishes all necessary files and sets up the package.

Publishing Individual Assets

# Publish configuration
php artisan vendor:publish --tag=flux-files-config

# Publish migrations
php artisan vendor:publish --tag=flux-files-migrations

# Publish models
php artisan vendor:publish --tag=flux-files-models

# Publish views
php artisan vendor:publish --tag=flux-files-views

# Publish language files
php artisan vendor:publish --tag=flux-files-lang

# Publish everything
php artisan vendor:publish --tag=flux-files

Testing

Run the package tests:

composer test

Run code analysis:

composer analyse

Format code:

composer pint

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

Security

If you discover any security-related issues, please email the maintainer instead of using the issue tracker.

Credits

idkwhoami
Built with FluxUI
Powered by Livewire

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see CHANGELOG.md for recent changes.

Flux Files - Making file management in Laravel applications elegant and effortless.

idkwhoami / flux-files

Maintainers

Details

README

Features

Requirements

Installation

Configuration

Usage

File Browser Component

File Selection Component

File Upload Component

Blade Components

File Display Components

Navigation Components

Upload Components

Models

File Model

Folder Model

Services

FileStorageService

FileValidationService

Advanced Usage

Multi-tenancy

Custom File Types

Events

Custom Views

Commands

Install Command

Publishing Individual Assets

Testing

Contributing

Security

Credits

License

Changelog