PHPackages                             gsebastiao/laravel-uploads - 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. gsebastiao/laravel-uploads

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

gsebastiao/laravel-uploads
==========================

Pacote Laravel para upload de arquivos (multipart e base64) com geração de thumbnails, metadados persistidos e organização por contexto.

v1.3.0(3w ago)011MITJavaScriptPHP >=8.2CI failing

Since Jul 11Pushed 3w agoCompare

[ Source](https://github.com/gsebastiao/laravel-uploads)[ Packagist](https://packagist.org/packages/gsebastiao/laravel-uploads)[ RSS](/packages/gsebastiao-laravel-uploads/feed)WikiDiscussions main Synced 1w ago

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

Laravel Uploads
===============

[](#laravel-uploads)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7654ab04babc3e5e323faa9c2dc2e8a9d6724194387a8ebca5081d8ac2b97edb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6773656261737469616f2f6c61726176656c2d75706c6f6164732e737667)](https://packagist.org/packages/gsebastiao/laravel-uploads)[![PHP Version](https://camo.githubusercontent.com/8e82de5e2258befc9145f32efa88110d4687a70f2081596edb12cff607f3077f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6773656261737469616f2f6c61726176656c2d75706c6f6164732e737667)](https://packagist.org/packages/gsebastiao/laravel-uploads)[![Laravel Version](https://camo.githubusercontent.com/599bcec48d5d03f0c3ec636be9f1ee1341f6b37299bb6cc0f933d1061ec0ca59/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31312e7825323025374325323031322e7825323025374325323031332e782d4646324432302e737667)](https://laravel.com)[![CI](https://github.com/gsebastiao/laravel-uploads/actions/workflows/ci.yml/badge.svg)](https://github.com/gsebastiao/laravel-uploads/actions/workflows/ci.yml)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

Pacote Laravel para upload de arquivos **multipart** e **base64**, com geração automática de thumbnails para imagens, persistência de metadados e associação polimórfica a qualquer model (morph).

Recursos
--------

[](#recursos)

- Upload de arquivos via `UploadedFile` (multipart) ou string base64 (com ou sem prefixo data URI).
- Associação polimórfica (`morphTo`): vincule cada arquivo a qualquer model (User, Post, etc.).
- API flexível: passe o **model direto** (`$user`) ou o **tipo + id** (`User::class, 42`).
- Nomes únicos por UUID e organização em `base_path/{group}/{YYYY}/{MM}/`, onde `{group}` deriva do tipo da entidade.
- 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
----------

[](#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
----------

[](#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

[](#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

[](#rodar-a-migration)

```
php artisan migrate
```

### Disco de armazenamento

[](#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
------------

[](#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',
];
```

ChaveDescrição`allowed_mimes`Extensões aceitas. A validação também confere o MIME real.`max_size`Tamanho máximo em KB.`base_path`Prefixo de diretório dentro do disco.`thumbnail.method``fit` mantém proporção; `resize` força as dimensões; `crop` recorta ao centro.`disk`Disco definido em `config/filesystems.php`.`url_prefix`Fallback de URL para discos sem `url()`.`auto_detect_uploader`Se `false`, `uploaded_by` nunca é preenchido automaticamente — só valores explícitos. Omissão: `true`.`auth_guard`Guard a verificar para detectar o utilizador autenticado. `null` usa o guard por omissão da aplicação.`assets_path`Destino (dentro de `public/`) do plugin JS ao publicar via `vendor:publish --tag=uploads-assets`.Associação polimórfica (morph)
------------------------------

[](#associação-polimórfica-morph)

Cada arquivo é vinculado a uma entidade via as colunas `reference_type` + `reference_id`. Você informa a referência de duas formas equivalentes:

```
// 1) Passando o model diretamente (tipo e id extraídos automaticamente)
Upload::uploadFile($request->file('avatar'), $user);

// 2) Passando o tipo + id (sem carregar o model)
Upload::uploadFile($request->file('avatar'), \App\Models\User::class, $userId);

// 3) Sem referência (arquivo "shared")
Upload::uploadFile($request->file('avatar'));
```

Para recuperar o dono a partir do arquivo, use a relação `reference`:

```
$file = Upload::getFile(123);
$owner = $file->reference; // instância de User, Post, etc.
```

Uso
---

[](#uso)

### Via Facade

[](#via-facade)

```
use Gsebastiao\LaravelUploads\Facades\Upload;

// Upload multipart vinculado a um model
$file = Upload::uploadFile($request->file('avatar'), $user);

// Upload base64 vinculado por tipo + id
$file = Upload::uploadBase64($base64String, \App\Models\Post::class, $postId);

// Recuperar, listar, remover
$file  = Upload::getFile(123);
$files = Upload::getFilesByReference($post);              // por model
$files = Upload::getFilesByReference(\App\Models\Post::class, $postId); // por tipo + id
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

[](#via-injeção-de-dependência)

```
use Gsebastiao\LaravelUploads\Contracts\UploadInterface;

public function __construct(private UploadInterface $uploads) {}

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

### Exemplo de Controller com validação de Request

[](#exemplo-de-controller-com-validação-de-request)

```