Download the PHP package whitecube/laravel-media without Composer

Laravel Media

Easily optimize and access images stored as attributes on Eloquent models.

Table of contents

1. Installation
2. Defining image attributes
3. Defining image variant generators
4. Displaying images
5. Roadmap

Installation

This package will auto-register its service provider.

Note: Make sure your configured filesystem disk can generate public URLs when using images in Blade views. For Laravel's public disk, this usually means running php artisan storage:link.

Defining image attributes

Getting started with laravel-media is quite simple as it mostly relies on Laravel's Mutators & Casting principles. All you'll have to do is define a mutator attribute representing the image that needs to be handled on the model:

This will return a Whitecube\Media\Image instance when accessing the model's attribute, providing useful methods for a proper display of the image:

More on the Whitecube\Media\Image class’s capabilities below.

Note: Laravel 13 (and earlier) does not allow objects to be assigned to a model's casts() array. Mutator attribute methods are currently the only way to go.

Configuring storage

By default, the package uses your application's default filesystem disk. You can change the disk and directory for each image attribute:

The model attribute will store a key representing the image. When using the filesystem repository, this key usually matches the filename or relative path inside the configured directory.

When the attribute is configured with ->path('posts'), assigning posts/cover.webp will automatically be normalized to cover.webp.

Defining variants

Variants are generated from the original file after the model is saved. You can define as many as needed in order to optimize the display, weight and format of the image for all situations.

You can also register variants one by one:

Variant generation will be automatically queued after the model is saved. Make sure your queue worker is configured and running when assigning or updating images (php artisan queue:work).

Placeholders

A placeholder can be defined on the attribute:

Or directly when displaying the image:

The placeholder image will be used for NULL values and when the original file is not found.

Custom getters and setters

You may pass custom getter and setter callbacks to Image::attribute() when the stored value needs to be adapted before the package handles it:

Custom repositories

The default repository reads files from the configured filesystem disk and does not rely on extra tables in your database. However, in some cases, for instance when building media libraries, you would need to store more information about uploaded and generated media. That is when a database-backed media repository becomes useful:

A repository must implement Whitecube\Media\Repositories\MediaRepository.

Note: This package is still a work in progress. A default DatabaseRepository will be added in a future version.

Defining image variant generators

Each variant generator needs to implement the Whitecube\Media\Generators\Variant contract, exposing three main methods:

• key: the variant's name, which can be used as the image's "default" or specifically requested;
• output: the variant's configuration definition, used to check the variant's expectations;
• generate: the actual method that will be called when a concrete variant needs to be created.

In this example, we're using intervention/image-laravel for our image manipulations, which has been seamlessly integrated into whitecube/laravel-media. You can, however, use any other library inside the generate method, as long as it returns a valid Whitecube\Media\MediaFile instance.

Output helpers

The Output object provides a few helpers to keep variant filenames and transformations predictable:

Available helpers include:

• Filename handling:
  • prefix() and suffix() to customize generated filenames;
  • useUniqueFilename() to generate a random filename;
• Image dimension management:
  • fit() to resize and crop an image to the given dimensions;
  • scale() to resize an image while maintaining the original aspect ratio;
• File storage management:
  • disk() and path() to override where the variant should be stored;
  • store() to write the generated file and return a MediaFile. It currently only supports intervention/image-laravel image objects.

The package currently ships with WebP output support, but other common formats will be added (feel free to open a PR).

Displaying images

Accessing an image attribute returns a Whitecube\Media\Image instance.

Displaying a specific variant

Use the variant key to request a generated variant:

If the requested variant does not exist yet, src() falls back to the original file, then to the configured placeholder (if defined).

Using the default variant

When a default variant is configured on the attribute, calling src() without arguments will use it automatically:

Checking if an image exists

You can also use isEmpty():

Accessing files directly

You can retrieve a concrete MediaFile instance for the original file or for a variant:

Casting to string

The image object can be rendered as a string. It will output the same value as src():

About alt, srcset and sizes

The alt() method currently returns the given fallback. In a future version, it is intended to look for a default value in the configured MediaRepository.

srcset() and sizes() are reserved for future responsive image support and currently return null.

Roadmap

• Adding a full version of the DatabaseRepository as the package's default media repository, enabling extension by media libraries.
• Adding new media types & documents.
• Adding media collections for galleries.
• Adding responsive image helpers such as srcset() and sizes().