PHPackages                             leorossi/laravel-image-s3 - 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. leorossi/laravel-image-s3

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

leorossi/laravel-image-s3
=========================

Upload images to S3/R2/local disk and generate configurable size/quality variants for Laravel.

00PHP

Pushed todayCompare

[ Source](https://github.com/leorossi/laravel-image-s3)[ Packagist](https://packagist.org/packages/leorossi/laravel-image-s3)[ RSS](/packages/leorossi-laravel-image-s3/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersionsUsed By (0)

Laravel Image S3
================

[](#laravel-image-s3)

A lightweight Laravel package to upload images to S3-compatible storage (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces) or a local disk, and automatically generate configurable size/quality variants.

Requirements
------------

[](#requirements)

- PHP `^8.2`
- Laravel `^11.0 | ^12.0 | ^13.0`
- GD extension (used by Intervention Image for processing)

Installation
------------

[](#installation)

```
composer require leorossi/laravel-image-s3
```

Publish the config file:

```
php artisan vendor:publish --tag=image-s3-config
```

If you want to publish migrations instead of using auto-discovery:

```
php artisan vendor:publish --tag=image-s3-migrations
```

Run migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

The published config file lives at `config/image-s3.php`.

```
return [
    'disk' => env('IMAGE_S3_DISK', 's3'),

    'original_directory' => 'original',
    'variants_directory' => 'variants',

    'queue' => [
        'enabled' => env('IMAGE_S3_QUEUE_ENABLED', false),
        'connection' => env('IMAGE_S3_QUEUE_CONNECTION', null),
        'queue' => env('IMAGE_S3_QUEUE_NAME', 'default'),
    ],

    'variants' => [
        'thumbnail' => [
            'width' => 150,
            'height' => 150,
            'quality' => 80,
            'fit' => 'cover',   // crop to exact size
        ],
        'medium' => [
            'width' => 800,
            'height' => 600,
            'quality' => 85,
            'fit' => 'contain', // fit inside dimensions
        ],
        'large' => [
            'width' => 1920,
            'height' => 1080,
            'quality' => 90,
            'fit' => 'contain',
        ],
    ],
];
```

### Adding custom variants

[](#adding-custom-variants)

You can add as many variants as you want. Each variant needs:

- `width` — target width in pixels
- `height` — target height in pixels
- `quality` — JPEG/WebP quality (0–100)
- `fit` — `cover` (crop to exact dimensions) or `contain` (fit inside dimensions)

Usage
-----

[](#usage)

### Upload an image

[](#upload-an-image)

```
use LeoRossi\LaravelImageS3\Facades\ImageS3;

$upload = ImageS3::upload($request->file('photo'), 'My photo alt text');

$upload->original_url;
$upload->variantUrl('thumbnail');
$upload->srcset();
```

### Using the service directly

[](#using-the-service-directly)

```
use LeoRossi\LaravelImageS3\Contracts\ImageUploaderInterface;

public function __construct(private ImageUploaderInterface $uploader) {}

$upload = $this->uploader->upload($request->file('photo'));
```

### Queue variant generation

[](#queue-variant-generation)

Set `queue.enabled` to `true` to process variants asynchronously. The original image is stored immediately; a `ProcessImageVariants` job is dispatched to generate variants.

### Delete an upload

[](#delete-an-upload)

Deleting the model also removes the original and all variants from storage:

```
$upload->delete();
```

Or use the facade/service:

```
ImageS3::delete($upload);
```

S3 / Cloudflare R2 Setup
------------------------

[](#s3--cloudflare-r2-setup)

Laravel does not include the S3 Flysystem adapter by default. Install it first:

```
composer require league/flysystem-aws-s3-v3
```

Configure your disk as usual in `config/filesystems.php`:

```
'r2' => [
    'driver' => 's3',
    'key' => env('CLOUDFLARE_R2_ACCESS_KEY_ID'),
    'secret' => env('CLOUDFLARE_R2_SECRET_ACCESS_KEY'),
    'region' => 'auto',
    'bucket' => env('CLOUDFLARE_R2_BUCKET'),
    'endpoint' => env('CLOUDFLARE_R2_ENDPOINT'),
    'use_path_style_endpoint' => true,
    'visibility' => 'public',
],
```

Then set `IMAGE_S3_DISK=r2` in your `.env`.

Testing
-------

[](#testing)

The package ships with PHPUnit tests using a local `testing` disk:

```
composer install
vendor/bin/phpunit
```

License
-------

[](#license)

MIT

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity8

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/604220?v=4)[Leonardo Rossi](/maintainers/leorossi)[@leorossi](https://github.com/leorossi)

---

Top Contributors

[![leorossi](https://avatars.githubusercontent.com/u/604220?v=4)](https://github.com/leorossi "leorossi (2 commits)")

### Embed Badge

![Health badge](/badges/leorossi-laravel-image-s3/health.svg)

```
[![Health](https://phpackages.com/badges/leorossi-laravel-image-s3/health.svg)](https://phpackages.com/packages/leorossi-laravel-image-s3)
```

###  Alternatives

[venveo/craft-compress

Create smart zip files from Craft assets on the fly

124.7k](/packages/venveo-craft-compress)

PHPackages © 2026

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