Download the PHP package elegantly/laravel-media without Composer

Flexible Media Library for Laravel

This package offers an extremely flexible media library, enabling you to store any type of file along with their conversions (nested conversions are supported). It is designed to work seamlessly with any filesystem solutions (local or cloud) such as Bunny.net, AWS S3/MediaConvert, Transloadit, among others.

The inspiration for this package is derived from the exceptional spatie/laravel-media-library package (be sure to check out Spatie's packages, they are top-notch). However, it is not a fork, as the internal architecture is different, providing you with more capabilities. Migration from spatie/laravel-media-library is feasible but may be challenging if you wish to retain your conversion files.

Motivation

The Spatie team has developed a remarkable package, spatie/laravel-media-library, which is well-suited for most common scenarios. However, I found myself constrained by their architecture for my own project. To address this, I required the following features:

• File transformations
• Advanced media conversions
• Nested media conversions

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

Full Example

The following example will provide you with a better understanding of the package's capabilities.

We will create a YouTube-like service, with a model named Channel. This Channel will have two types of media: avatar and videos. We will define these media types in the registerMediaCollections method.

We want to store the avatars in a square format, with dimensions not exceeding 500px, and in the WebP format. We will accomplish this in the registerMediaTransformations method.

For each media type, we will need a set of conversions, as illustrated in the following tree:

We will define these conversions in the registerMediaConversions method.

Here is how our Channel class will be defined:

From now, we will be able to store files in the easiest way possible:

Storing a file from a Controller

Storing a file from a Livewire component

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

Introduction to the Concepts

There are two essential concepts to understand, both of which are associated with the Model and its media:

• Media Collection: This defines a group of media with its specific settings (the group can only contain one media item). For example, avatar, thumbnail, and upload are all media collections.

• Media Conversion: This defines a file conversion of a particular media item. For instance, a 720p version of a larger 1440p video, a WebP or PNG conversion of an image, are all examples of media conversions. Notably, a media conversion can also have its own media conversions.

Usage

Preparing Your Models

This package is designed to associate media with a model, but it can also be used without any model association.

Registering Media Collections

First, you need to add the HasMedia trait and the InteractWithMedia interface to your Model:

You can then define your media collections in the registerMediaCollections method:

Registering Media Conversions

This package provides common jobs for your conversions to simplify your work:

• VideoPosterConversionJob: This job extracts a poster using pbmedia/laravel-ffmpeg.
• OptimizedVideoConversionJob: This job optimizes, resizes, or converts any video using pbmedia/laravel-ffmpeg.
• OptimizedImageConversionJob: This job optimizes, resizes, or converts any image using spatie/image.
• ResponsiveImagesConversionsPreset: This preset creates a set of optimized images of different sizes.
• ResponsiveVideosConversionsPreset: This preset creates a set of optimized videos of different sizes.

Defining Your Own MediaConversion

You can create your own conversion by creating a new class in your app (e.g., App\Support\MediaConversions) and extending MediaConversionJob.

Media conversions are executed through Laravel Jobs. You can perform any task in the job, provided that:

• Your job extends Elegantly\Media\Jobs\MediaConversion.
• Your job defines a run method.
• Your job calls $this->media->storeConversion(...).

Let's consider a common media conversion task: optimizing an image. Here's how you could implement it in your app:

Note: The following job is already provided by this package, but it serves as an excellent introduction to the concept.

Using Your Own 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.