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(3mo ago)056MITPHPPHP ^8.0

Since Feb 11Pushed 3mo 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 1mo 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

36

—

LowBetter than 82% of packages

Maintenance82

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity42

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

95d 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

[unisharp/laravel-filemanager

A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE

2.2k3.3M74](/packages/unisharp-laravel-filemanager)[aws/aws-sdk-php-laravel

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

1.7k35.6M75](/packages/aws-aws-sdk-php-laravel)[yoelpc4/laravel-cloudinary

Laravel Cloudinary filesystem cloud driver.

3343.0k](/packages/yoelpc4-laravel-cloudinary)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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