Download the PHP package finller/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
   • onAdded MediaCollection Callback
   • onCompleted MediaConversionDefinition Callback
   • Custom conversions
   • Manually generate conversions
   • Format Media Url

5. Customization

   • Custom Media Model
6. Troubleshooting
   • Ghostscript and Imagick Issues

Requirements

• PHP 8.1+
• Laravel 11.0+
• spatie/image for image conversions
• spatie/pdf-to-image for PDF to 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:

onAdded MediaCollection Callback

The onAdded callback allows you to define custom logic that will be executed whenever new media is added to your collection.

To use it, simply set the onAdded parameter when defining a MediaCollection. For example:

With this, you can easily hook into the media addition process and trigger actions like sending notifications, logging, or other custom behavior.

[!TIP] The same behavior can be achieved by listening to Elegantly\Media\Events\MediaAddedEvent.

onCompleted MediaConversionDefinition Callback

The onCompleted callback allows you to define custom logic that will be executed whenever a new conversion is generated.

To use it, simply set the onCompleted parameter when defining a MediaConversionDefinition. For example:

This allows you to hook into the conversion process and execute additional logic, such as updating your UI or triggering other actions.

[!TIP] The same behavior can be achieved by listening to Elegantly\Media\Events\MediaConversionAddedEvent.

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.

Format Media URLs

Some cloud providers like Cloudflare, Bunny, or ImageKit allow you to create instant transformations of your images and videos using specially formatted URLs.

This package gives you a simple way to format your URLs so you can take advantage of these services.

When using the $media->getUrl() method, you can specify two parameters:

• parameters: An array of values
• formatter: The class name of the formatter you want to use

By combining these parameters, you can retrieve formatted URLs like this:

This package comes with 3 formatters out of the box:

• \Elegantly\Media\UrlFormatters\DefaultUrlFormatter
• \Elegantly\Media\UrlFormatters\CloudflareImageUrlFormatter
• \Elegantly\Media\UrlFormatters\CloudflareVideoUrlFormatter

Feel free to implement your own formatter by extending \Elegantly\Media\UrlFormatters\AbstractUrlFormatter.

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:

Troubleshooting

Ghostscript and Imagick Issues

This package relies on the spatie/pdf-to-image library, which uses Ghostscript via Imagick to convert PDFs into images.

If you encounter errors while generating images from PDFs, such as:

• attempt to perform an operation not allowed by the security policy 'PDF'
• Uncaught ImagickException: FailedToExecuteCommand 'gs'

these issues are likely related to the configuration of Ghostscript or Imagick on your system.

For detailed guidance on resolving these errors, refer to the spatie/pdf-to-image documentation on Ghostscript issues.

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.