Download the PHP package elegantly/laravel-media without Composer

Extremely powerful media library for Laravel 🖼️

This package offers an extremely flexible media library, enabling you to store any type of file along with their conversions.

It provides advanced features such as:

• 🌐 Supports any filesystem solutions (local or cloud), such as S3, R2, Bunny.net, DO...
• ⚡ Supports any file conversion solutions (local or cloud), such as ffmpeg, Transloadit, Cloudflare, Coconut, and others.
• 🔄 Advanced nested media conversions
• 🚀 Rich metadata automatically extracted
• 🛠️ Highly flexible and customizable

I developed this package with the highest degree of flexibility possible and I have been using it in production for nearly a year, handling terabytes of files monthly.

Table of Contents

1. Requirements

2. Installation

3. Basic Usage

   • Define Media Collection
   • Define Media Conversions
   • Adding Media
   • Retreiving Media
   • Media properties
   • Accessing Media Conversions
   • Blade components

4. Advanced Usage

   • Async vs Sync conversions
   • Delayed conversions
   • Custom conversions
   • Manually generate conversions
5. Customization
   • Custom Media Model

Requirements

• PHP 8.1+
• Laravel 11.0+
• spatie/image for image conversions
• ffmpeg & pbmedia/laravel-ffmpeg for video/audio processing

Installation

You can install the package via composer:

You have to publish and run the migrations with:

You can publish the config file with:

This is the contents of the published config file:

Optionally, you can publish the views using

Basic Usage

Defining Media Collections

Media Collections define how media are stored, transformed, and processed for a specific model. They provide granular control over file handling, accepted types, and transformations.

To associate a media collection with a Model, start by adding the InteractWithMedia interface and the HasMedia trait.

Next, define your collections in the registerMediaCollections method, as shown below:

Defining Media Conversions

Media conversions create different variants of your media files. For example, a 720p version of a 1440p video or a WebP or PNG version of an image are common types of media conversions. Interestingly, a media conversion can also have its own additional conversions.

This package provides common converions to simplify your work:

• MediaConversionImage: This conversion optimizes, resizes, or converts any image using spatie/image.
• MediaConversionVideo: This conversion optimizes, resizes, or converts any video using pbmedia/laravel-ffmpeg.
• MediaConversionAudio: This conversion optimizes, resizes, converts or extract any audio using pbmedia/laravel-ffmpeg.
• MediaConversionPoster: This conversion extracts a poster using pbmedia/laravel-ffmpeg.

Adding Media

Add media to your model from various sources:

From a Controller

From a Livewire Component

Retreiving Media

Retrieve media from your model:

Media properties

Each media item provides rich metadata automatically:

You can use dot notation to access either the root properties or a specific conversion:

Access Media Conversions

To directly access conversions, use:

Blade components

The package also provides blade components.

Advanced Usage

Async vs. Sync Conversions

When adding new media, its conversions can be either dispatched asynchronously or generated synchronously.

You can configure the strategy in the conversion definition using the queued and queue parameters:

Synchronous conversions can be particularly useful in specific use cases, such as generating a poster immediately upon upload.

Delayed Conversions

There are scenarios where you might want to define conversions that should not be generated immediately. For instance, if a conversion is resource-intensive or not always required, you can defer its generation to a later time.

To achieve this, configure the conversion with the immediate parameter set to false. This allows you to generate the conversion manually when needed:

To generate the conversion later, you can use the following methods:

Custom Conversions

Conversions can be anything—a variant of a file, a transcription of a video, a completely new file, or even just a string.

You can use built-in presets or define your own custom conversion. To create a custom conversion, use the MediaConversionDefinition class:

The handle method of MediaConversionDefinition is where the logic for the conversion is implemented. It provides the following parameters:

• $media: The Media model.
• $parent: The MediaConversion model, if the conversion is nested.
• $file: A local copy of the file associated with either $media or $parent.
• $filesystem: An instance of the local filesystem where the file copy is stored.
• $temporaryDirectory: An instance of TemporaryDirectory where the file copy is temporarily stored.

You don’t need to worry about cleaning up the files, as the $temporaryDirectory will be deleted automatically when the process completes.

To finalize the conversion, ensure you save it by calling $media->addConversion or returning a MediaConversion instance at the end of the handle method.

Manually Generate Conversions

You can manage your media conversions programmatically using the following methods:

Additionally, you can use an Artisan command to generate conversions with various options:

This provides a convenient way to process conversions in bulk or automate them within your workflows.

Customization

Custom Media Model

You can define your own Media model to use with the library.

First, create your own model class:

Then, update the config file:

The library is typed with generics, so you can use your own Media model seamlessly:

Testing

Changelog

Please see the CHANGELOG for more information on recent changes.

Contributing

Feel free to open an issue or a discussion.

Security Vulnerabilities

Please contact me to report security vulnerabilities.

Credits

• Quentin Gabriele
• All Contributors

License

The MIT License (MIT). Please see the License File for more information.