Laravel Uploads

Pacote Laravel para upload de arquivos multipart e base64, com geração automática de thumbnails para imagens, persistência de metadados e organização por contexto.

Recursos

• Upload de arquivos via UploadedFile (multipart) ou string base64 (com ou sem prefixo data URI).
• Nomes únicos por UUID e organização em base_path/{context}/{YYYY}/{MM}/.
• Metadados persistidos na tabela uploads_files (dimensões, MIME, tamanho, thumbnail, etc.).
• Thumbnails automáticas para imagens (fit, resize ou crop) via Intervention Image v3.
• Validação configurável de extensões/MIME e tamanho máximo.
• Soft deletes e remoção permanente (arquivo + registro).
• Facade Upload e binding via container (UploadInterface).

Requisitos

• PHP >= 8.2 (Laravel 13 exige PHP >= 8.3)
• Laravel 11.x, 12.x ou 13.x
• Extensão GD (ou Imagick) para thumbnails

Instalação

composer require gsebastiao/laravel-uploads

O pacote usa auto-discovery do Laravel; o service provider e o alias Upload são registrados automaticamente.

Publicar configuração e migrations

php artisan vendor:publish --tag=uploads

Isso publica config/uploads.php e a migration da tabela. Também é possível publicar separadamente:

php artisan vendor:publish --tag=uploads-config
php artisan vendor:publish --tag=uploads-migrations

Rodar a migration

php artisan migrate

Disco de armazenamento

O pacote usa o disco public por padrão. Garanta que o link simbólico existe:

php artisan storage:link

Configuração

config/uploads.php:

return [
    'allowed_mimes' => ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'doc', 'docx'],
    'max_size' => 10240, // KB (10 MB)
    'base_path' => 'uploads',
    'thumbnail' => [
        'enabled' => true,
        'width' => 120,
        'height' => 120,
        'quality' => 80,
        'method' => 'fit', // fit, resize, crop
    ],
    'disk' => 'public',
    'url_prefix' => '/storage',
];

Uso

Via Facade

use Gsebastiao\Uploads\Facades\Upload;

// Upload multipart
$file = Upload::uploadFile($request->file('avatar'), 'user_avatar', $userId);

// Upload base64 (com ou sem prefixo data URI)
$file = Upload::uploadBase64($base64String, 'post_image', $postId);

// Recuperar, listar, remover
$file  = Upload::getFile(123);
$files = Upload::getFilesByContext('post_image', $postId);
Upload::deleteFile(123);          // soft delete
Upload::deleteFile(123, true);    // remoção permanente

// URL pública
$url = Upload::getFileUrl($file);

Via injeção de dependência

use Gsebastiao\Uploads\Contracts\UploadInterface;

public function __construct(private UploadInterface $uploads) {}

public function store(Request $request)
{
    $file = $this->uploads->uploadFile($request->file('doc'), 'documents');
    // ...
}

Exemplo de Controller com validação de Request

<?php

namespace App\Http\Controllers;

use Gsebastiao\Uploads\Facades\Upload;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function updateAvatar(Request $request, int $userId)
    {
        $request->validate([
            'avatar' => 'required|file|mimes:jpg,jpeg,png|max:2048',
        ]);

        try {
            $file = Upload::uploadFile(
                $request->file('avatar'),
                'user_avatar',
                $userId
            );

            return response()->json([
                'success' => true,
                'data'    => $file,
                'url'     => Upload::getFileUrl($file),
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage(),
            ], 400);
        }
    }
}

Exemplo base64

$base64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...';

$file = Upload::uploadBase64($base64, 'post_image', $postId, 'capa.png');

API do serviço

Tratamento de erros

• Gsebastiao\Uploads\Exceptions\ValidationException — extensão/MIME não permitido ou tamanho excedido.
• Gsebastiao\Uploads\Exceptions\UploadException — falha na gravação, base64 inválido, etc.

Todas as operações são registradas via Log.

Estrutura da tabela uploads_files

id, context, reference_id, filename, original_name, path, full_path, size, ext, mime, width, height, thumbnail, status, created_at, updated_at, deleted_at.

Testes

composer install
vendor/bin/phpunit

Análise estática (opcional)

vendor/bin/phpstan analyse

Licença

MIT. Veja LICENSE.