Download the PHP package daycode/stup-images without Composer

Laravel Stup Image

Image uploads for Laravel without tables or migrations. One statement to validate, resize, convert and store an image on any disk.

That single statement checks the real MIME type, resizes, converts to WebP, gives the file a unique name, writes it to your disk (local, public, S3, ...) and returns the path to save in your database. You don't need a media table, a migration or any setup.

Contents

• Features
• Requirements
• Installation
• Quick start
• Usage
  • Storing an image
  • Resizing
  • Formats and quality
  • Disks, directories, names and visibility
  • Replacing an image
  • Multiple images
  • Deleting and URLs
  • Presets
  • Variants
  • Eloquent integration
  • UploadedFile macro
  • Events
  • Error handling
• Testing
• Configuration
• Stup Image or Spatie Media Library?
• Upgrading from v1
• Security
• Contributing
• Credits and license

Features

• One fluent statement covers validation, processing and storage.
• Any disk: images are encoded in memory and written with Storage::disk()->put(), so local, public, S3, R2, Spaces and other disks all work.
• Safe validation: the MIME type is detected from the file contents, not from the client extension. There are limits for file size and dimensions.
• Resize: cover, scale, contain and resize, powered by Intervention Image with GD or Imagick.
• Convert to WebP, AVIF, JPEG or PNG and set the quality.
• Unique names by default (ULID). UUID, random hash, the slugged original name or your own namer are also available.
• Safe replace: the old image is deleted only after the new one has been stored.
• Batches are all-or-nothing: if one file fails, the files already stored are removed again.
• Presets and variants: define named sizes once, then store extra sizes such as thumb and medium next to the image, either during the request or on the queue.
• Eloquent trait: assign an UploadedFile to an attribute. The file is stored, and the old one is deleted after the model saves.
• StupImage::fake() with assertions for your own tests.
• ImageStored / ImageDeleted events.

Requirements

You also need the PHP gd or imagick extension.

Installation

The service provider and the StupImage facade are auto-discovered. You can optionally publish the config and check your image driver:

If you store images on the public disk, link the storage folder once:

Quick start

Store the path ($image->path, for example avatars/01j9zk3v7c8e2x4m6n8p0q2r4s.webp) in your database. With the path you can build URLs, delete or replace the image later without remembering the directory.

Usage

Storing an image

Resizing

Operations run in the order you call them. Use when() to apply one conditionally:

Formats and quality

The original format is kept unless you convert it:

You can also set default_format in the config to convert every upload, for example to WebP.

Disks, directories, names and visibility

Replacing an image

The old image, including its variants, is deleted only after the new image has been stored. If the new upload fails, the old one stays. $user->avatar may be null.

Multiple images

If any file fails, the files already stored are removed again and the exception is rethrown.

Deleting and URLs

Deleting a missing file doesn't throw. delete() returns false in that case.

Presets

Define named option sets in config/stup-image.php:

Presets support the keys resize, cover, scale, contain (as [width, height]), format and quality. Options you call after preset() override the preset.

Variants

Store extra sizes next to the image in one go:

Variants are generated from the original upload. A variant uses its preset's format, or the image's format when the preset has none. delete() and replace() remove the variants of every configured preset too.

To generate the variants on the queue instead of during the request, add queue():

Queued variants are generated from the stored image, so apply size-reducing options only through variants when you queue them.

Eloquent integration

• The column stores the path, so you still need a nullable string column. No extra tables are involved.
• Old images are deleted only after the model has been saved.
• Deleting the model deletes its images. With SoftDeletes, they're deleted on forceDelete().
• A failed upload aborts the save and removes any image stored by that save.

UploadedFile macro

Events

Error handling

Every failure throws a subclass of Daycode\StupImage\Exceptions\StupImageException:

A wrong configuration or argument (unknown preset, invalid quality, ...) throws an InvalidArgumentException.

You should still validate requests with Laravel's image, mimes and max rules so users get friendly messages. Stup Image's checks are the safety net behind them.

Testing

StupImage::fake() fakes every disk the package uses. Images are still processed for real, so dimensions and formats are accurate, and every operation is recorded:

Available assertions: assertStored(?path|callback, ?times), assertStoredCount(), assertNothingStored(), assertDeleted(), assertNotDeleted() and assertNothingDeleted(). You can also read the records with storedImages() and deletedImages().

Configuration

About visibility: new S3 buckets have ACLs disabled, and setting a visibility makes uploads to them fail. That's why the default is null.

About original naming: the client filename is slugged (My Photo.JPG → my-photo.jpg) and deduplicated (my-photo-1.jpg).

For a custom naming strategy, implement Daycode\StupImage\Contracts\Namer and set its class name in naming.

Stup Image or Spatie Media Library?

spatie/laravel-medialibrary is an excellent, far more complete package. Here's a comparison to help you pick:

Pick Stup Image when you want an avatar, cover or product image stored with a path in an existing column, and nothing more. Pick Spatie Media Library when you manage many files per model, non-image files, custom properties or responsive images.

Upgrading from v1

v2 is a rewrite, but the v1 Stupable trait still works as a deprecated wrapper, so you can upgrade gradually. See UPGRADE.md for the breaking changes and the v1 → v2 mapping.

Security

• The MIME type is detected from the file contents (finfo). A file renamed to .jpg is rejected.
• Only the bytes of the upload are decoded, never a path, and only the default image MIME types are allowed. SVG is not allowed.
• Filenames are generated (ULID) by default, so client filenames never reach your disk.
• For untrusted uploads, consider setting max_width/max_height. Decoding a very large image uses a lot of memory.

If you discover a security vulnerability, please follow SECURITY.md.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md. Before you open a PR, run these:

See CHANGELOG.md for what's new.

Credits and license

• Author: Wirandra Alaya (dayCod)
• Image processing: Intervention Image
• All contributors

Stup Image is open-source software licensed under the GitHub.