backpack / medialibrary-uploaders
Helper functions to save files with spatie media library
Installs: 26 589
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 2
Forks: 4
Open Issues: 5
Requires
- backpack/crud: ^6.0
- spatie/laravel-medialibrary: ^10.7|^11.3
Requires (Dev)
- orchestra/testbench: ~6|^8.0
- phpunit/phpunit: ^9.0|^10.0
This package is auto-updated.
Last update: 2024-11-04 15:24:20 UTC
README
If you project uses both Spatie Media Library and Backpack for Laravel, 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. You'll love how simple it makes uploads!
Requirements
Install and use spatie/laravel-medialibrary
v10. If you haven't already, please make sure you've installed spatie/laravel-medialibrary
and followed all installation steps in their docs:
# require the package composer require "spatie/laravel-medialibrary:^10.0.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.
Installation
Just require this package using Composer, that's it:
composer require backpack/medialibrary-uploaders
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
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)
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 shoudn'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
You can also have the collection configured in your model as explained in Spatie Documentation, 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
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 aditional manipulations in the `whenSaving` callback ->withMedia([ 'displayConversions' => 'thumb', 'whenSaving' => function($media) { return $media->withManipulations([ 'thumb' => ['orientation' => 90] ]); } ]);
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
Changes are documented here on Github. Please see the Releases tab.
Testing
composer test
Contributing
Please see contributing.md for a todolist and howtos.
Security
If you discover any security related issues, please email hello@backpackforlaravel.com instead of using the issue tracker.
Credits
- Pedro Martins - author & architect
- Cristian Tabacitu - reviewer
- Backpack for Laravel - sponsor
- All Contributors
License
This project was released under MIT, so you can install it on top of any Backpack & Laravel project. Please see the license file for more information.