← Back to Plugins
  • Media Library Manager

Media Library Manager

Plugin information

by Ralph J. Smit

Admin panel Field Kit Spatie Form builder

Give your users a beautiful way to upload, manage and select media and images in Filament Admin. Integrates with Spatie MediaLibrary.

Support

#media-library-pro on Discord

Views

7866

License

Custom

Documentation

This package allows you to give your users a beautiful way to upload images to your application and manage their library. It integrates with and is based on Spatie MediaLibrary, one of the most popular and widely used packages in the Laravel ecosystem.

Features

Screenshots

Library (light and dark mode)

The MediaLibrary page is the page where your users can view all their images. The complete package is compatible with both dark- and lightmode.

Media Library page

Media Library page Dark Mode

Upload & bulk upload

Users can drag-and-drop their images unto the upload component. Bulk uploads are allowed. You can use Laravel's queue processing feature to handle the process of generating responsive images in the background.

Filament MediaLibrary regular upload

Media Library Bulk Upload

Filament Media Library Bulk Upload

MediaPicker Field & modal

You can use the MediaPicker Field everywhere inside the admin panel where you want it: as a single field or in a repeater. It works everywhere.

MediaPicker Field & modal

When a user clicks on 'Choose image', he/she will see the following modal, which they can use to pick an image.

Filament MediaPicker Modal

Image detail

For each image, you can edit the caption and the alt-text. You can view the full image URL in the browser and delete images as well.

Filament MediaLibrary Image Detail

Image detail vertical

Default theme

By default Filament comes with it's own CSS, which integrates neatly into the admin panel design. However, as I did in the above screenshots, it is just as beautiful if you integrate it with your own Filament theme.

Filament MediaLibrary With Default Theme



Installation guide: A Convenient Media Library for Filament Admin

Thank you for purchasing the ultimate Media Library plugin for Filament Admin!

We tried to make the library as easy-to-install and versatile as possible. Nevertheless, if you still have a question or a feature request, please send an e-mail to [email protected].

In this guide I'll show you how to install the library, so you can start using it right away.

Contents

Installation

Prerequisites

For these installation instructions to work, you'll need to have the Filament Admin package installed and configured.

The package makes use of the Spatie MediaLibrary package. If you already have this package installed, you can skip this step.

We'll need to publish the required migration first by running the following Artisan command.

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"

The package is supported on both Laravel 8 and 9. Please be aware though that support for security fixes for Laravel 8 ends within a few months.

You'll also need to have the ImageMagick PHP-extension installed on your system for the image conversions to happen. This is a relatively common extension and required by the underlying Spatie media library plugin. If you are using Laravel Sail, check out the section below.

Installing ImageMagick on Laravel Sail

If you use Laravel Sail, installing ImageMagick requires a few additional steps. To get started, try the following steps:

  1. First, run php artisan sail:publish to publish your DockerFiles.
  2. Then, open the DockerFile that corresponds to your PHP version (e.g. docker/8.1/docker/Dockerfile for PHP 8.1).
  3. Add the php8.1-imagick to the line with the PHP extensions (use the correct PHP version).
  4. Run php artisan sail build --no-cache.
  5. Restart the container and continue with the installation.

Installation via Composer

To install the package you should add the package to your composer.json file in the repositories key:

{
"repositories": [
{
"type": "composer",
"url": "https://filament-media-library-pro.composer.sh"
}
],
}

Next, you should require the package via the command line. You will be prompted for your username (which is your e-mail) and your password (which is your license key plus a colon ':' + the domain on which you activated it, e.g. 8c21df8f-6273-4932-b4ba-8bcc723ef500:mydomain.com).

composer require ralphjsmit/laravel-filament-media-library

After purchasing the plugin, you'll also be shown installation instructions with the appropriate credentials pre-filled.

Finally, you'll need to publish the migration and migrate the database:

php artisan vendor:publish --tag="filament-media-library-migrations"
 
php artisan migrate

Custom themes

If you're using a custom theme, you'll need to instruct Tailwind to also purge the view-files for the media library. Add the following key to the content key of your tailwind.config.js file:

content: [
// Your other files
'./vendor/ralphjsmit/laravel-filament-media-library/resources/**/*.blade.php'
],

Next, you'll also need to disable the loading of our default stylesheet, because we don't want to load unnecessary CSS. Set the filament-media-library.register.default_css to false.

Usage

Using the media library is very simple. After installing it, you should see a new page in your sidebar called "Media library". On this page your users can upload images, view their other images, edit metadata and delete images.

Technical details

It might be handy to know a bit about how the media library works under-the-hood. Each item in your media library is an instance of the RalphJSmit\Filament\MediaLibrary\Media\Models\MediaLibraryItem Eloquent model. This model is used to store metadata about the image.

For example, if you have 10 images in your library, you will also have 10 MediaLibraryItem models with metadata.

Manually adding uploaded files

Adding an image can be done via the static addUpload method on the MediaLibraryItem class. This method accepts an instance of Illuminate\Http\UploadedFile.

use RalphJSmit\Filament\MediaLibrary\Media\Models\MediaLibraryItem;
 
$uploadedFile = /** */;
 
$mediaItem = MediaLibraryItem::addUpload($uploadedFile);

You only need to know the above information if you want to manually add uploaded files.

The image files itself are being stored by the Spatie MediaLibrary package. The files are stored in a collection called library.

Manually adding files from a path

Sometimes you don't have an instance of an UploadedFile ready, but you only have a path to the image. That situation is also possible, though it requires a little bit more work.

$path = /** */;
 
$originalFileName = 'test.jpg';
 
$uploadedFile = UploadedFile::createFromBase(new \Symfony\Component\HttpFoundation\File\UploadedFile($path, $originalFileName));
 
MediaLibraryItem::addUpload($uploadedFile);

Customizing the page

If you want to override the title or navigation label, you can create a new class in your project that extends the \RalphJSmit\Filament\MediaLibrary\Media\Pages\MediaLibrary page. In this class you can override everything you want to customize, like the title, navigation label or navigatin group.

Finally, you should update the filament-media-library.register.pages config option to use your own new page instead of the default page.

MediaPicker

This plugin comes with a custom Filament field called a MediaPicker. This field can be used to choose an image from the library. The field looks like this:

MediaPicker Field & modal

The field can be used anywhere you want: it behaves just like a normal field.

The field consists of two things:

  1. A part that is always visible.
  2. A modal to browse the actual media library.

Include the field like this:

MediaPicker::make('image')
->label('Choose image')
->required(),

The value of the field will be the id of the MediaLibraryItem that is being selected.

Displaying images on your site

The MediaPicker component will store the id of the MediaLibraryItem model. To display an image, you can use that id to find the appropriate model.

Each model has a related Spatie\MediaLibrary\MediaCollections\Models\Media model. You can use this Media model to retrieve URLs, paths & other properties. You can use all the methods described in the Spatie MediaLibrary documentation.

$id = /** You stored this */
 
$mediaLibraryItem = MediaLibraryItem::find($id);
 
$spatieMediaModel = $mediaLibraryItem->getItem();
 
$url = $spatieMediaModel->getUrl();
$path = $spatieMediaModel->getPath();
 
//

We also provided support for the responsive images feature from Spatie.

Deleting an image

If you want to delete an image, please delete the MediaLibraryItem model and not Spatie's Media model. Spatie's Media model is automatically deleted when you delete the original MediaLibraryItem model.

Policies

The media library package offers support for policies. This allows you to determine whether a user can create a new media library item or delete an old item.

Supported checks are:

First, create a policy (e.g. in app/Policies) with the following contents:

<?php
 
namespace App\Policies;
 
class MediaLibraryItemPolicy
{
public function create(User $user): bool
{
//
}
 
public function delete(User $user, MediaLibraryItem $mediaLibraryItem): bool
{
//
}
}

Next, open up your AuthServiceProvider and register the policy for the model:

protected $policies = [
MediaLibraryItem::class => MediaLibraryItemPolicy::class,
];

Now you are ready and the create and delete actions are governed by a policy.

Registering custom media conversions

By default, the plugin registers four media conversions. The media conversions are:

  1. responsive
  2. 400
  3. 800
  4. thumb

These conversions are used throughout the plugin, so you cannot remove them. However, you are free to register additional media conversions using the MediaLibrary::registerMediaConversions() function:

use RalphJSmit\Filament\MediaLibrary\Facades\MediaLibrary;
 
MediaLibrary::registerMediaConversions(function (MediaLibraryItem $mediaLibraryItem, Media $media = null) {
$mediaLibraryItem
->addMediaConversion('test');
 
// ..
});

You are free to register as many conversions as you like.

Changing the conversion for thumbnails

By default, the plugin generates a square media conversion called thumb that is used to display each media item in the library.

If you wish, you can change the conversion that is displayed in the library by updating the filament-media-library.thumbnail-media-conversion in the config:

// You can change the media conversion that is used to display the previews in the library.
// The default conversion is `thumb`. This conversion is a square conversion and generated
// automatically already. However, you can change the conversion to any other conversion.
// Please keep in mind that square conversions that aren't large work best.
'thumbnail-media-conversion' => 'thumb',

Enable uploading videos & PDFs

The media library also has support for uploading videos & PDFs. By default, these options are disabled, because they might need the installation of an addition library.

You can enable video and PDF-support using the configuration file:

// You can specify the filetypes you want your users to be able to upload.
'accepted_filetypes' => [
// There is no additional configuration needed for accepting images.
'image' => true,
 
// In order to upload PDFs, you need to have the "spatie/pdf-to-image" package configured correctly.
// This package is already required via Composer, but you need to make sure that the extension for
// imagick has been installed and that Ghostscript is installed. Check out the following link:
// https://github.com/spatie/pdf-to-image#requirements
'pdf' => false,
 
// In order to let your users upload videos, you need to have the FFmpeg binary installed. See
// the website of FFmpeg for installation instructions: https://ffmpeg.org/download.html.
'video' => false,
],

Overriding custom classes

The plugin provides several configuration options to override the internal classes it uses. This can be handy in situations where you want to make a small tweak to a certain behaviour or design.

Make sure to always extend the original class.

// Use the below setting to customize the model used for media library items.
// This allows you to override the model for an iten and customize it.
// Make sure to always extend the original model, so that you will not accidentally
// lose functionality or forget to upgrade functions.
'models' => [
'item' => MediaLibraryItem::class,
],
// The resources and pages to enable in your application.
'register' => [
// From the below array, you can remove the pages you don't need.
// If you want to modify a page yourself, you can extend the original page
// and register your own class here that extends the page. In that way, you can
// customize labels, titles, etc.
'pages' => [
MediaLibrary::class,
],
 
// The below three classes are the main Livewire-components. If you want to modify
// one of the classes, you can create a new class that extends the original class
// and update the configuration here accordingly.
// NB.: Please note that I cannot guarantee that breaking changes will never happen
// inside these classes, so be sure to check if your changes still work after each update.
'livewire' => [
'upload-media' => UploadMedia::class,
'media-info' => MediaInfo::class,
'browse-library' => BrowseLibrary::class,
],
 
// ..
],

NB.: Please note that I cannot guarantee that breaking changes will never happen inside these classes, so be sure to check if your changes still work after each update.

Using the MediaPicker outside the admin panel

It is also very easy to use the MediaPicker component outside the admin panel. To enable support for this, you should include the @mediaPickerModal Blade-directive on every page where you want to use the MediaPicker component.

The @mediaPickerModal directive should be added before the </body>-tag. Please make sure to only include the component once to prevent issues.

<!-- In your app.blade.php -->
<body>
 
<!-- ... -->
@mediaPickerModal
</body>

Or, on individual pages only:

@once
@mediaPickerModal
@endonce

Support

If you have a question or feature request, please e-mail me at [email protected]

🐞 If you spot a bug, please submit a detailed issue and I'll try to fix it as soon as possible.

🔐 If you discover a vulnerability, please review our security policy.

🙋‍♂️ Ralph J. Smit