PHPackages                             wramirez83/fluxupload - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. wramirez83/fluxupload

ActiveLibrary[File & Storage](/categories/file-storage)

wramirez83/fluxupload
=====================

Laravel package for large file uploads using chunking with automatic resumption

3.1.0(1mo ago)111MITHTMLPHP ^8.1

Since Nov 16Pushed 1mo agoCompare

[ Source](https://github.com/wramirez83/FluxUpload)[ Packagist](https://packagist.org/packages/wramirez83/fluxupload)[ RSS](/packages/wramirez83-fluxupload/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (6)Used By (0)

FluxUpload v3.1.0 - Laravel Package for Large File Uploads
==========================================================

[](#fluxupload-v310---laravel-package-for-large-file-uploads)

FluxUpload es un paquete Laravel que permite la subida de archivos grandes (superiores a 1GB) mediante chunking (división en partes) con capacidad de reanudación automática.

📋 Características
-----------------

[](#-características)

- ✅ Subida de archivos grandes (hasta 25GB)
- ✅ Chunking automático (división en partes)
- ✅ Reanudación automática de cargas interrumpidas
- ✅ Validación de integridad mediante hash (opcional)
- ✅ Soporte para múltiples discos de almacenamiento (Local, S3, MinIO, Azure Blob)
- ✅ API REST completa
- ✅ Cliente JavaScript incluido
- ✅ Eventos para integración
- ✅ Limpieza automática de sesiones expiradas
- ✅ Compatible con Laravel 11, 12 y 13

📦 Instalación
-------------

[](#-instalación)

### Requisitos

[](#requisitos)

- PHP 8.1 o superior (compatible con PHP 8.4)
- Laravel 11, 12 o 13 (`illuminate/support` ^11.0, ^12.0 o ^13.0)
- **Laravel 13** exige PHP **8.3+** según el framework; en PHP 8.4 el paquete se ejecuta y prueba sin cambios adicionales
- Extensiones PHP: `fileinfo`, `mbstring`, `openssl`, `json`

### Instalación vía Composer

[](#instalación-vía-composer)

```
composer require wramirez83/fluxupload
```

**Versión actual**: 3.1.0

### Publicar configuración y migraciones

[](#publicar-configuración-y-migraciones)

```
php artisan vendor:publish --tag=fluxupload-config
php artisan vendor:publish --tag=fluxupload-migrations
```

### Ejecutar migraciones

[](#ejecutar-migraciones)

```
php artisan migrate
```

### Publicar assets JavaScript (opcional)

[](#publicar-assets-javascript-opcional)

```
php artisan vendor:publish --tag=fluxupload-assets
```

⚙️ Configuración
----------------

[](#️-configuración)

El archivo de configuración se encuentra en `config/fluxupload.php`. Puedes configurar:

```
// Tamaño de chunk por defecto (2MB en v3.0.0)
'chunk_size' => env('FLUXUPLOAD_CHUNK_SIZE', 2097152),

// Tamaño máximo de archivo (25GB en v3.0.0)
'max_file_size' => env('FLUXUPLOAD_MAX_FILE_SIZE', 26843545600),

// Expiración de sesiones (24 horas)
'session_expiration_hours' => env('FLUXUPLOAD_SESSION_EXPIRATION', 24),

// Disco de almacenamiento
'storage_disk' => env('FLUXUPLOAD_STORAGE_DISK', 'local'),

// Ruta de almacenamiento
'storage_path' => env('FLUXUPLOAD_STORAGE_PATH', 'fluxupload'),

// Extensiones permitidas (vacío = todas)
'allowed_extensions' => env('FLUXUPLOAD_ALLOWED_EXTENSIONS')
    ? explode(',', env('FLUXUPLOAD_ALLOWED_EXTENSIONS'))
    : [],

// Validar hash
'validate_hash' => env('FLUXUPLOAD_VALIDATE_HASH', false),
'hash_algorithm' => env('FLUXUPLOAD_HASH_ALGORITHM', 'sha256'),
```

### Variables de entorno

[](#variables-de-entorno)

Puedes configurar el paquete mediante variables de entorno en tu archivo `.env`:

```
FLUXUPLOAD_CHUNK_SIZE=2097152
FLUXUPLOAD_MAX_FILE_SIZE=26843545600
FLUXUPLOAD_SESSION_EXPIRATION=24
FLUXUPLOAD_STORAGE_DISK=local
FLUXUPLOAD_STORAGE_PATH=fluxupload
FLUXUPLOAD_ALLOWED_EXTENSIONS=pdf,doc,docx,zip
FLUXUPLOAD_VALIDATE_HASH=true
FLUXUPLOAD_HASH_ALGORITHM=sha256
FLUXUPLOAD_ROUTE_PREFIX=fluxupload
FLUXUPLOAD_MIDDLEWARE=api
```

🚀 Uso Básico
------------

[](#-uso-básico)

### API REST

[](#api-rest)

#### 1. Inicializar sesión de subida

[](#1-inicializar-sesión-de-subida)

```
POST /fluxupload/init
Content-Type: application/json

{
    "filename": "documento.pdf",
    "total_size": 104857600,
    "chunk_size": 2097152,
    "mime_type": "application/pdf",
    "hash": "sha256_hash_here" // opcional
}
```

**Respuesta:**

```
{
    "success": true,
    "session_id": "abc123...",
    "total_chunks": 50,
    "chunk_size": 2097152,
    "uploaded_chunks": 0,
    "missing_chunks": [0, 1, 2, ..., 19],
    "progress": 0
}
```

#### 2. Subir chunk

[](#2-subir-chunk)

```
POST /fluxupload/chunk
Content-Type: multipart/form-data

session_id: abc123...
chunk_index: 0
chunk: [archivo binario]
```

**Respuesta:**

```
{
    "success": true,
    "message": "Chunk uploaded successfully",
    "session_id": "abc123...",
    "chunk_index": 0,
    "uploaded_chunks": 1,
    "total_chunks": 50,
    "progress": 5.0,
    "status": "uploading"
}
```

#### 3. Consultar estado

[](#3-consultar-estado)

```
GET /fluxupload/status/{session_id}
```

**Respuesta:**

```
{
    "success": true,
    "session_id": "abc123...",
    "filename": "documento.pdf",
    "status": "uploading",
    "uploaded_chunks": 25,
    "total_chunks": 50,
    "total_size": 104857600,
    "progress": 50.0,
    "missing_chunks": [25, 26, 27, ..., 49],
    "storage_path": null,
    "error_message": null,
    "expires_at": "2024-01-01T12:00:00Z"
}
```

### Cliente JavaScript

[](#cliente-javascript)

#### Uso básico

[](#uso-básico)

```

const uploader = new FluxUpload({
    baseUrl: '/fluxupload',
    chunkSize: 2 * 1024 * 1024, // 2MB (v3.0.0)
    parallelUploads: 3,
    onProgress: (progress) => {
        console.log(`Progress: ${progress.progress}%`);
    },
    onComplete: (status) => {
        console.log('Upload completed!', status);
    },
    onError: (error) => {
        console.error('Upload error:', error);
    }
});

// Subir archivo
const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (e) => {
    const file = e.target.files[0];
    try {
        await uploader.upload(file);
    } catch (error) {
        console.error('Upload failed:', error);
    }
});

```

#### Reanudar subida

[](#reanudar-subida)

```
// Si tienes un session_id previo
uploader.sessionId = 'previous-session-id';
await uploader.resume();
```

#### Pausar/Cancelar

[](#pausarcancelar)

```
// Pausar
uploader.pause();

// Cancelar
uploader.cancel();
```

### Uso en PHP (Backend)

[](#uso-en-php-backend)

```
use Wramirez83\FluxUpload\Facades\FluxUpload;

// Obtener servicios
$uploadService = FluxUpload::getUploadService();
$sessionService = FluxUpload::getSessionService();
$chunkService = FluxUpload::getChunkService();

// Crear sesión manualmente
$session = $sessionService->createSession([
    'original_filename' => 'archivo.pdf',
    'total_size' => 104857600,
    'total_chunks' => 50,
    'chunk_size' => 2097152,
]);

// Obtener chunks faltantes
$missingChunks = $sessionService->getMissingChunks($session->session_id);

// Ensamblar archivo manualmente
$uploadService->assembleFile($session);
```

📡 Eventos
---------

[](#-eventos)

FluxUpload emite eventos que puedes escuchar:

### FluxUploadCompleted

[](#fluxuploadcompleted)

Se emite cuando una subida se completa exitosamente.

```
use Wramirez83\FluxUpload\Events\FluxUploadCompleted;
use Illuminate\Support\Facades\Event;

Event::listen(FluxUploadCompleted::class, function (FluxUploadCompleted $event) {
    $session = $event->session;

    // Procesar archivo completado
    // $session->storage_path contiene la ruta del archivo final
    // $session->storage_disk contiene el disco donde se guardó
});
```

### FluxUploadFailed

[](#fluxuploadfailed)

Se emite cuando una subida falla.

```
use Wramirez83\FluxUpload\Events\FluxUploadFailed;

Event::listen(FluxUploadFailed::class, function (FluxUploadFailed $event) {
    $session = $event->session;
    $error = $event->errorMessage;

    // Manejar error
    logger()->error("Upload failed: {$error}", [
        'session_id' => $session->session_id,
    ]);
});
```

### FluxUploadChunkReceived

[](#fluxuploadchunkreceived)

Se emite cada vez que se recibe un chunk (opcional).

```
use Wramirez83\FluxUpload\Events\FluxUploadChunkReceived;

Event::listen(FluxUploadChunkReceived::class, function (FluxUploadChunkReceived $event) {
    $session = $event->session;
    $chunk = $event->chunk;

    // Procesar chunk recibido
});
```

🧹 Limpieza de Sesiones
----------------------

[](#-limpieza-de-sesiones)

### Comando Artisan

[](#comando-artisan)

Para limpiar sesiones expiradas manualmente:

```
php artisan fluxupload:clean
```

### Modo dry-run

[](#modo-dry-run)

Para ver qué se eliminaría sin eliminar realmente:

```
php artisan fluxupload:clean --dry-run
```

### Programar limpieza automática

[](#programar-limpieza-automática)

En **Laravel 11 y posteriores** suele definirse en `routes/console.php`. En versiones anteriores, en `app/Console/Kernel.php`:

```
use Illuminate\Support\Facades\Schedule;

Schedule::command('fluxupload:clean')
    ->daily()
    ->at('02:00');
```

Si aún usas `Kernel` con el método `schedule`:

```
protected function schedule(Schedule $schedule)
{
    $schedule->command('fluxupload:clean')
        ->daily()
        ->at('02:00');
}
```

🔒 Seguridad
-----------

[](#-seguridad)

### Autenticación

[](#autenticación)

Puedes proteger las rutas mediante middleware. En `config/fluxupload.php`:

```
'middleware' => ['api', 'auth:sanctum'],
```

O usando middleware personalizado:

```
'middleware' => ['api', 'throttle:60,1'],
```

### Validación de extensiones

[](#validación-de-extensiones)

```
'allowed_extensions' => ['pdf', 'doc', 'docx', 'zip'],
```

### Validación de hash

[](#validación-de-hash)

Para validar la integridad del archivo:

```
'validate_hash' => true,
'hash_algorithm' => 'sha256', // o 'md5'
```

🧪 Pruebas
---------

[](#-pruebas)

Ejecutar todas las pruebas:

```
composer test
```

O con PHPUnit directamente:

```
./vendor/bin/phpunit
```

### Estructura de pruebas

[](#estructura-de-pruebas)

- `tests/Unit/` - Pruebas unitarias de servicios y modelos
- `tests/Feature/` - Pruebas de integración de la API

📚 Ejemplos
----------

[](#-ejemplos)

### Ejemplo completo con JavaScript

[](#ejemplo-completo-con-javascript)

```
>

    FluxUpload Example

    Upload
    Pause
    Resume

        const uploader = new FluxUpload({
            baseUrl: '/fluxupload',
            chunkSize: 2 * 1024 * 1024, // 2MB (v3.0.0)
            parallelUploads: 3,
            onProgress: (progress) => {
                document.getElementById('progress').textContent =
                    `Progress: ${progress.progress}% (${progress.uploaded}/${progress.total})`;
            },
            onComplete: (status) => {
                alert('Upload completed!');
                console.log('File saved at:', status.storage_path);
            },
            onError: (error) => {
                alert('Upload failed: ' + error.message);
            }
        });

        document.getElementById('uploadBtn').addEventListener('click', async () => {
            const fileInput = document.getElementById('fileInput');
            if (fileInput.files.length > 0) {
                try {
                    await uploader.upload(fileInput.files[0]);
                } catch (error) {
                    console.error(error);
                }
            }
        });

        document.getElementById('pauseBtn').addEventListener('click', () => {
            uploader.pause();
        });

        document.getElementById('resumeBtn').addEventListener('click', async () => {
            try {
                await uploader.resume();
            } catch (error) {
                console.error(error);
            }
        });

```

### Ejemplo con React

[](#ejemplo-con-react)

```
import { useState } from 'react';
import FluxUpload from './fluxupload';

function FileUploader() {
    const [progress, setProgress] = useState(0);
    const [uploader] = useState(() => new FluxUpload({
        baseUrl: '/fluxupload',
        onProgress: (p) => setProgress(p.progress),
        onComplete: (status) => {
            console.log('Completed:', status);
            setProgress(100);
        },
        onError: (error) => {
            console.error('Error:', error);
        }
    }));

    const handleFileChange = async (e) => {
        const file = e.target.files[0];
        if (file) {
            await uploader.upload(file);
        }
    };

    return (

            Progress: {progress}%

    );
}
```

🐛 Solución de Problemas
-----------------------

[](#-solución-de-problemas)

### Error: "Session not found"

[](#error-session-not-found)

- Verifica que el `session_id` sea correcto
- Verifica que la sesión no haya expirado
- Revisa los logs de Laravel

### Error: "Chunk size validation failed"

[](#error-chunk-size-validation-failed)

- Verifica que el tamaño del chunk coincida con el configurado
- El último chunk puede ser más pequeño que el tamaño configurado

### Archivo no se ensambla correctamente

[](#archivo-no-se-ensambla-correctamente)

- Verifica que todos los chunks se hayan subido
- Revisa los permisos de escritura en el directorio de chunks
- Verifica el espacio en disco disponible

📝 Changelog
-----------

[](#-changelog)

Ver [CHANGELOG.md](CHANGELOG.md) para más detalles.

🤝 Contribuir
------------

[](#-contribuir)

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

📄 Licencia
----------

[](#-licencia)

Este paquete es de código abierto bajo la [licencia MIT](LICENSE).

👥 Autores
---------

[](#-autores)

- **Medusa** - *Desarrollo inicial*

🙏 Agradecimientos
-----------------

[](#-agradecimientos)

- Laravel Framework
- Comunidad de desarrolladores PHP

---

**¿Necesitas ayuda?** Abre un issue en GitHub o contacta al equipo de desarrollo.

###  Health Score

42

—

FairBetter than 89% of packages

Maintenance98

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~34 days

Total

5

Last Release

37d ago

Major Versions

1.0.2 → 2.0.02025-11-16

2.0.0 → 3.0.02025-11-17

### Community

Maintainers

![](https://www.gravatar.com/avatar/dd11480feff23989c23a202a8601179e35a4dc5430c17fbcc67db23f3bbcac8e?d=identicon)[wramirez83](/maintainers/wramirez83)

---

Top Contributors

[![wramirez83](https://avatars.githubusercontent.com/u/14268794?v=4)](https://github.com/wramirez83 "wramirez83 (11 commits)")

---

Tags

laravelfile-uploadlarge fileschunkingresumable-upload

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wramirez83-fluxupload/health.svg)

```
[![Health](https://phpackages.com/badges/wramirez83-fluxupload/health.svg)](https://phpackages.com/packages/wramirez83-fluxupload)
```

###  Alternatives

[aws/aws-sdk-php-laravel

A simple Laravel 9/10/11/12/13 service provider for including the AWS SDK for PHP.

1.7k35.6M74](/packages/aws-aws-sdk-php-laravel)[spatie/laravel-google-cloud-storage

Google Cloud Storage filesystem driver for Laravel

2408.9M12](/packages/spatie-laravel-google-cloud-storage)[jildertmiedema/laravel-plupload

Laravel/Plupload - Handle large file uploads

177232.7k](/packages/jildertmiedema-laravel-plupload)[fojuth/plupload

A Laravel 4 implementation of Plupload (http://www.plupload.com/).

162.5k](/packages/fojuth-plupload)[kingofcode/laravel-uploadable

Laravel Uploadable trait to automatically upload images and files with minimum configuration

286.4k](/packages/kingofcode-laravel-uploadable)[zing/laravel-flysystem-obs

Flysystem Adapter for OBS

1211.2k](/packages/zing-laravel-flysystem-obs)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)