PHPackages                             tannhatcms/medialibrary-uploaders - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. tannhatcms/medialibrary-uploaders

ActiveLibrary[File & Storage](/categories/file-storage)

tannhatcms/medialibrary-uploaders
=================================

Helper functions to save files with spatie media library

1.2.2(5mo ago)04MIT

Since Mar 3Pushed 5mo agoCompare

[ Source](https://github.com/TanNhatCMS/Laravel-Backpack-medialibrary-uploaders)[ Packagist](https://packagist.org/packages/tannhatcms/medialibrary-uploaders)[ Docs](https://github.com/backpack/medialibrary-uploaders)[ RSS](/packages/tannhatcms-medialibrary-uploaders/feed)WikiDiscussions dev Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (13)Used By (0)

Spatie Media Library Uploaders for Backpack CRUD fields & columns
=====================================================================

[](#spatie-media-library-uploaders-for-backpack-crud-fields--columns)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9a571bd696b8e5f8a49041f27e3db9cc64880036e820c54364cf1a143f8e5414/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6261636b7061636b2f6d656469616c6962726172792d75706c6f61646572732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backpack/medialibrary-uploaders)[![Total Downloads](https://camo.githubusercontent.com/d2dc2ff4fb432397ae50698e7be1dd79807484129b5a4b36a0952325d37ab77f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6261636b7061636b2f6d656469616c6962726172792d75706c6f61646572732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/backpack/medialibrary-uploaders)[![The Whole Fruit Manifesto](https://camo.githubusercontent.com/9fc65ecdd629dc33c369f73e0bc051740f01647367c131a574577fea2a5678bb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f77726974696e672532307374616e646172642d74686525323077686f6c6525323066727569742d627269676874677265656e)](https://github.com/the-whole-fruit/manifesto)

If you project uses both [Spatie Media Library](https://github.com/spatie/laravel-medialibrary) and [Backpack for Laravel](https://backpackforlaravel.com/), this add-on provides the ability for:

- Backpack fields to easily store uploaded files as media (by using Spatie Media Library);
- Backpack columns to easily retrieve uploaded files as media;

More exactly, it provides the `->withMedia()` helper, that will handle the file upload and retrieval using [Backpack Uploaders](https://backpackforlaravel.com/docs/%7B%7Bversion%7D%7D/crud-uploaders). You'll love how simple it makes uploads!

Requirements
------------

[](#requirements)

**Install and use `spatie/laravel-medialibrary` v10|v11**. If you haven't already, please make sure you've installed `spatie/laravel-medialibrary` and followed all installation steps in [their docs](https://spatie.be/docs/laravel-medialibrary/v11/installation-setup):

```
# require the package
composer require "spatie/laravel-medialibrary:^11.0"

# prepare the database
# NOTE: Spatie migration does not come with a `down()` method by default, add one now if you need it
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"

# run the migration
php artisan migrate

# make sure you have your storage symbolic links created for the default laravel `public` disk
php artisan storage:link

# (optionally) publish the config file
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"
```

Then prepare your Models to use `spatie/laravel-medialibrary`, by adding the `InteractsWithMedia` trait to your model and implement the `HasMedia` interface like explained on [Media Library Documentation](https://spatie.be/docs/laravel-medialibrary/v11/basic-usage/preparing-your-model).

Installation
------------

[](#installation)

Just require this package using Composer, that's it:

```
composer require backpack/medialibrary-uploaders
```

Usage
-----

[](#usage)

On any field where you upload a file (eg. `upload`, `upload_multiple`, `image` or `dropzone`), add `withMedia()` to your field definition, in order to tell Backpack to store those uploaded files using Spatie's Laravel MediaLibrary. For example:

```
CRUD::field('avatar')->type('image')->withMedia();

// you can also do that on columns:
CRUD::column('avatar')->type('image')->withMedia();

// and on subfields:
CRUD::field('gallery')
        ->label('Image Gallery')
        ->type('repeatable')
        ->subfields([
            [
                'name' => 'main_image',
                'label' => 'Main Image',
                'type' => 'image',
                'withMedia' => true,
            ],
        ]);
```

Advanced Use
------------

[](#advanced-use)

### Overriding the defaults

[](#overriding-the-defaults)

Backpack sets up some handy defaults for you when handling the media. But it also provides you a way to customize the bits you need from Spatie Media Library. You can pass a configuration array to `->withMedia([])` or `'withMedia' => []` to override the defaults Backpack has set.

```
CRUD::field('main_image')
        ->label('Main Image')
        ->type('image')
        ->withMedia([
            'collection' => 'my_collection', // default: the spatie config default
            'disk' => 'my_disk', // default: the spatie config default
            'mediaName' => 'custom_media_name' // default: the field name
        ]);
```

### Customizing the saving process (adding thumbnails, responsive images etc)

[](#customizing-the-saving-process-adding-thumbnails-responsive-images--etc)

Inside the same configuration array mentioned above, you can use the `whenSaving` closure to customize the saving process. This closure will be called in THE MIDDLE of configuring the media collection. So AFTER calling the initializer function, but BEFORE calling toMediaCollection(). Do what you want to the $spatieMedia object, using Spatie's documented methods, then `return` it back to Backpack to call the termination method. Sounds good?

```
CRUD::field('main_image')
        ->label('Main Image')
        ->type('image')
        ->withMedia([
            'whenSaving' => function($spatieMedia, $backpackMediaObject) {
                return $spatieMedia->usingFileName('main_image.jpg')
                                    ->withResponsiveImages();
            }
        ]);
```

**NOTE:** Some methods will be called automatically by Backpack; You shouldn't call them inside the closure used for configuration: `toMediaCollection()`, `setName()`, `usingName()`, `setOrder()`, `toMediaCollectionFromRemote()` and `toMediaLibrary()`. They will throw an error if you manually try to call them in the closure.

### Defining media collection in the model

[](#defining-media-collection-in-the-model)

You can also have the collection configured in your model as explained in [Spatie Documentation](https://spatie.be/docs/laravel-medialibrary/v11/working-with-media-collections/defining-media-collections), in that case, you just need to pass the `collection` configuration key. But you are still able to configure all the other options including the `whenSaving` callback.

```
// In your Model.php

public function registerMediaCollections(): void
{
    $this
        ->addMediaCollection('product_images')
        ->useDisk('products');
}

// And in YourCrudController.php
CRUD::field('main_image')
        ->label('Main Image')
        ->type('image')
        ->withMedia([
            'collection' => 'product_images', // will pick the collection definition from your model
        ]);
```

### Working with Conversions

[](#working-with-conversions)

Sometimes you will want to create conversions for your images, like thumbnails etc. In case you want to display some conversions instead of the original image on the field you should define `displayConversions => 'conversion_name'` or `displayConversions => ['higher_priority_conversion', 'second_priority_conversion']`.

In the end, if none of the conversions are ready yet (maybe they are still queued), we will display the original file as a fallback.

```
// In your Model.php

public function registerMediaConversions(): void
{
    $this->addMediaConversion('thumb')
                ->width(368)
                ->height(232)
                ->keepOriginalImageFormat()
                ->nonQueued();
}

// And in YourCrudController.php
CRUD::field('main_image')
        ->label('Main Image')
        ->type('image')
        ->withMedia([
            'displayConversions' => 'thumb'
        ]);

// you can also configure additional manipulations in the `whenSaving` callback
->withMedia([
    'displayConversions' => 'thumb',
    'whenSaving' => function($media) {
        return $media->withManipulations([
            'thumb' => ['orientation' => 90]
        ]);
    }
]);
```

### Custom properties

[](#custom-properties)

You can normally assign custom properties to your media with `->withCustomProperties([])` as stated in spatie documentation, but please be advise that `name`, `repeatableContainerName` and `repeatableRow` are **reserved keywords** and Backpack values will **always** overwrite yours.

```
'whenSaving' => function($media) {
        return $media->withCustomProperties([
            'my_property' => 'value',
            'name' => 'i_cant_use_this_key'
        ]);
    }

// the saved custom properties will be:
//  - [my_property => value, name => main_image, repeatableRow => null, repeatableContainerName => null]`
```

Change log
----------

[](#change-log)

Changes are documented here on Github. Please see the [Releases tab](https://github.com/Laravel-Backpack/medialibrary-uploaders/releases).

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Please see [contributing.md](contributing.md) for a todolist and howtos.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Pedro Martins](https://github.com/pxpm/) - author & architect
- [Cristian Tabacitu](https://github.com/tabacitu) - reviewer
- [Backpack for Laravel](https://github.com/laravel-backpack) - sponsor
- [All Contributors](../../contributors)

License
-------

[](#license)

This project was released under MIT, so you can install it on top of any Backpack & Laravel project. Please see the [license file](license.md) for more information.

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance70

Regular maintenance activity

Popularity3

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~145 days

Recently: every ~177 days

Total

7

Last Release

175d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/bfa34fbe26304da44b94d720c13ab86b5b5841faac4a2cc9eeaaab4ee6ab193b?d=identicon)[TanNhatCMS](/maintainers/TanNhatCMS)

---

Top Contributors

[![pxpm](https://avatars.githubusercontent.com/u/7188159?v=4)](https://github.com/pxpm "pxpm (96 commits)")[![tabacitu](https://avatars.githubusercontent.com/u/1032474?v=4)](https://github.com/tabacitu "tabacitu (17 commits)")[![TanNhatCMS](https://avatars.githubusercontent.com/u/113796420?v=4)](https://github.com/TanNhatCMS "TanNhatCMS (1 commits)")

---

Tags

laravelbackpackBackpack for LaravelBackpack Addonspatie medialibrary uploaders

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tannhatcms-medialibrary-uploaders/health.svg)

```
[![Health](https://phpackages.com/badges/tannhatcms-medialibrary-uploaders/health.svg)](https://phpackages.com/packages/tannhatcms-medialibrary-uploaders)
```

###  Alternatives

[backpack/medialibrary-uploaders

Helper functions to save files with spatie media library

1373.3k](/packages/backpack-medialibrary-uploaders)[backpack/theme-tabler

UI for Backpack v6 that uses Tabler and Bootstrap v5.

35536.5k](/packages/backpack-theme-tabler)[backpack/activity-log

Activity Log for Backpack

3487.5k1](/packages/backpack-activity-log)[backpack/translation-manager

Translation Manager for Backpack

5118.9k1](/packages/backpack-translation-manager)[gaspertrix/laravel-backpack-dropzone-field

Add Dropzone support for Laravel Backpack

172.2k](/packages/gaspertrix-laravel-backpack-dropzone-field)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)