PHPackages                             hercilioln/simple-upload - 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. hercilioln/simple-upload

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

hercilioln/simple-upload
========================

A simple and robust file upload manager for Laravel (Supports Local & S3).

v2.0.0(6mo ago)089MITPHPPHP ^8.0

Since Feb 11Pushed 6mo agoCompare

[ Source](https://github.com/hercilioln/simple-upload)[ Packagist](https://packagist.org/packages/hercilioln/simple-upload)[ RSS](/packages/hercilioln-simple-upload/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (3)Dependencies (4)Versions (5)Used By (0)

SimpleUpload for Laravel
========================

[](#simpleupload-for-laravel)

[![Portuguese Version](https://camo.githubusercontent.com/52b314f28e95692448efd2f5190c629d5f338b92a8d1d4d8366f74238aea7f71/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f506f72747567756573652d56657273696f6e2d677265656e)](README_PT.md)

A lightweight and robust file upload manager for Laravel.

It abstracts the repetitive logic of **checking, deleting old files, and uploading new ones**, keeping your controllers clean and DRY.

It works seamlessly with **Local** and **Amazon S3** (or any driver configured in your filesystem).

🚀 Installation
--------------

[](#-installation)

You can install the package via composer:

```
composer require hercilio/simple-upload
```

⚙️ Configuration
----------------

[](#️-configuration)

The package automatically uses the default disk defined in your `.env` file.

```
# For local development
FILESYSTEM_DISK=local

# For production (AWS S3, MinIO, DigitalOcean Spaces, etc)
FILESYSTEM_DISK=s3
```

💡 Usage
-------

[](#-usage)

First, import the Facade in your Controller:

```
use Hercilio\SimpleUpload\Facades\SimpleUpload;
```

### 1. Simple Upload (Unique Hash)

[](#1-simple-upload-unique-hash)

Ideal for avatars and images where the original filename doesn't matter.

```
// Saves to storage/app/avatars/unique-hash.jpg
$path = SimpleUpload::upload($request->file('avatar'), 'avatars');
```

### 2. Upload with Custom Name

[](#2-upload-with-custom-name)

You can specify a custom filename (without extension):

```
// Saved as: avatars/profile-photo.jpg
$path = SimpleUpload::upload(
    $request->file('avatar'),
    'avatars',
    'profile-photo'
);
```

### 3. Upload with Original Name (Sanitized) ✨

[](#3-upload-with-original-name-sanitized-)

Ideal for documents (PDFs, spreadsheets) where you want to preserve the filename. The package automatically removes accents and spaces.

```
// Input file: "Financial Report 2026.pdf"
// Saved as: "docs/financial-report-2026.pdf"
$path = SimpleUpload::uploadAsOriginal($request->file('doc'), 'docs');
```

### 4. Force a Specific Disk (Optional)

[](#4-force-a-specific-disk-optional)

If you need to save to a specific disk other than the default one, pass it as the **last parameter**:

```
// With custom name and specific disk
SimpleUpload::upload($file, 'backups', 'monthly-backup', 's3');

// Without custom name, only specific disk
SimpleUpload::upload($file, 'backups', null, 's3');

// Upload as original with specific disk
SimpleUpload::uploadAsOriginal($file, 'docs', 's3');
```

### 5. The "Killer Feature": Painless Updates 🔥

[](#5-the-killer-feature-painless-updates-)

Replacing a file usually requires boilerplate code: check if the new file exists, check if the old file exists, delete the old one, upload the new one. `SimpleUpload` handles this in a single line.

```
public function update(Request $request, User $user)
{
    // If the user uploaded a new photo:
    // 1. Deletes the old photo ($user->photo_path)
    // 2. Uploads the new one
    // 3. Returns the new path
    // If no file was uploaded, it simply returns the old path.

    $path = SimpleUpload::update(
        $request->file('photo'),
        $user->photo_path,
        'users'
    );

    $user->update(['photo_path' => $path]);
}
```

You can also specify a disk for updates:

```
$path = SimpleUpload::update(
    $request->file('photo'),
    $user->photo_path,
    'users',
    's3'
);
```

📋 Method Signatures
-------------------

[](#-method-signatures)

```
// Main upload method
upload(?UploadedFile $file, string $folder = 'uploads', ?string $customName = null, ?string $disk = null)

// Upload with original name
uploadAsOriginal(?UploadedFile $file, string $folder = 'uploads', ?string $disk = null)

// Update existing file
update(?UploadedFile $newFile, ?string $currentPath, string $folder = 'uploads', ?string $disk = null)

// Delete file
delete(?string $path, ?string $disk = null)
```

📝 License
---------

[](#-license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

34

—

LowBetter than 74% of packages

Maintenance68

Regular maintenance activity

Popularity11

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

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 ~0 days

Total

4

Last Release

187d ago

Major Versions

v1.2.1 → v2.0.02026-02-12

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/58452038?v=4)[Hercilio Lopes](/maintainers/hercilioln)[@hercilioln](https://github.com/hercilioln)

### Embed Badge

![Health badge](/badges/hercilioln-simple-upload/health.svg)

```
[![Health](https://phpackages.com/badges/hercilioln-simple-upload/health.svg)](https://phpackages.com/packages/hercilioln-simple-upload)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[mike-bronner/laravel-model-caching

Automatic caching for Eloquent models.

2.4k161.4k2](/packages/mike-bronner-laravel-model-caching)[illuminate/auth

The Illuminate Auth package.

9328.5M1.4k](/packages/illuminate-auth)[illuminate/routing

The Illuminate Routing package.

1239.4M3.5k](/packages/illuminate-routing)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45844.8k1](/packages/pressbooks-pressbooks)

PHPackages © 2026

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