finnwiel / shazzoo-media
A media library for Laravel
Requires
- php: ^8.1
- awcodes/filament-curator: ^3.0
- filament/filament: ^3.0
- illuminate/support: ^10.0 || ^11.0 || ^12.0
- intervention/image: ^2.7
- livewire/livewire: ^3.0
- spatie/laravel-package-tools: ^1.0
Requires (Dev)
- orchestra/testbench: ^8.0
- phpunit/phpunit: ^10.0
README
A Laravel + Filament plugin that extends Filament Curator with custom media conversion logic and a customized media model.
Installation
⚠️ Important: Before installing, make sure the GD extension is enabled in your php.ini. Without it, image conversions will fail and no thumbnails will be generated.
You can install the package via composer then run the installation command:
composer require finnwiel/shazzoo-media
If you installed Curator before Shazzoo Media, you’ll need to remove Curator’s media table migration manually before running the install command.
php artisan shazzoo_media:install
Note: This plugin will install curator for you but you will have to do some of the setup. Like installing CropperJS and using a custom filament theme for styling. If you have not set up a custom theme and are using a Panel follow the instructions in the Filament Docs first.
npm install -D cropperjs
Import the plugin's stylesheet and cropperjs' stylesheet into your theme's css file.
@import '<path-to-vendor>/awcodes/filament-curator/resources/css/plugin.css';
Add the plugin's views to your custom theme's tailwind.config.js
file.
content: [ './vendor/awcodes/filament-curator/resources/**/*.blade.php', './vendor/finnwiel/shazzoo-media/resources/views/components/**/*.blade.php', ]
Usage
Global settings
The plugins settings can be managed through the config file
php artisan vendor:publish --tag=shazzoo_media-config
Note: This plugin will also change some of curators settings, you can still manage curators setting but they may not work with Shazzoo Media
To publish the plugins Model run:
php artisan vendor:publish --tag=shazzoo-media-model
Filament Panels
If you are using Filament Panels you will need to add the Plugin to your Panel's configuration. This will register the plugin's resources with the Panel. All methods are optional, and will be read from the config file if not provided.
public function panel(Panel $panel): Panel { return $panel ->colors([ 'primary' => Color::Amber, 'secondary' => Color::Cyan, // Add a secondary color ]) ->plugins([ \Awcodes\Curator\CuratorPlugin::make() ->label('Media') ->navigationLabel('Media Library') ->resource(MediaResource::class) // use FinnWiel\ShazzooMedia\Resources\MediaResource; ->registerNavigation(true) ->navigationCountBadge(true) ]) }
Picker field
Shazzoo Media adds a conversions method to the picker field, this method accepts an array. The conversions will subsequently be set in the database for each array item. Shazzoo Media will also create the conversion image.
ShazzooMediaCuratorPicker::make('featured_image_id') ->conversions(['thumbnail']),
To generate actually set the conversions in the database you need to add a trait to the create and edit classes of your resource.
use FinnWiel\ShazzooMedia\Traits\HandlesConversions; class CreatePost extends CreateRecord { use HandlesConversions; protected static string $resource = PostResource::class; }
Conversions
Conversions are set in config/shazzoo_media.php
in the conversions array. To add or remove conversions change the array with the same structure.
'conversions' => [ 'profile' => ['width' => 80, 'height' => 80], 'thumbnail' => ['width' => 200, 'height' => 200], 'medium' => ['width' => 400, 'height' => 400], 'large' => ['width' => 600, 'height' => 600], ],
So adding a new conversion called small would look like this:
'conversions' => [ 'profile' => ['width' => 80, 'height' => 80, 'fit' => 'crop'], 'thumbnail' => ['width' => 200, 'height' => 200], 'medium' => ['width' => 400, 'height' => 400], 'large' => ['width' => 600, 'height' => 600], 'small' => ['width' => 100, 'height' => 100], ],
As you can see the existing conversions can also be edited, this can even be done when some conversions have already been made. Just be sure to run the php artisan media:conversions:regenerate
command. This will regenerate the conversions to the new sizes.
Showing images
To show images in your frontend using the ShazzooMedia
model, you can leverage the built-in dynamic URL accessors for media conversions.
For each image conversion defined in your config (shazzoo_media.conversions), a dynamic property is available on your media model:
$image->thumbnail_url // returns URL for the 'thumbnail' conversion $image->web_url // returns URL for the 'web' conversion
If the conversion file exists, it returns the converted image URL. If not, it gracefully falls back to the original image URL.
Example in blade:
<img src="{{ $media->thumbnail_url }}" alt="Thumbnail">
Defining relationships
You are responsible for defining the relationship between your Eloquent models and the media records.
One-to-One Example:
For a model that has a single media item, like a Post
with a featured image:
// In your Post.php model use FinnWiel\ShazzooMedia\Models\ShazzooMedia; public function featuredImage() { return $this->belongsTo(ShazzooMedia::class, 'media_id'); }
Usage:
<img src="{{ $post->featuredImage?->thumbnail_url }}" alt="Featured image">
One-to-Many Example:
For a model that has multiple images, like a Product
with a gallery:
// In your Product.php model use FinnWiel\ShazzooMedia\Models\ShazzooMedia; public function gallery() { return $this->hasMany(ShazzooMedia::class, 'product_id'); }
Usage:
@foreach($product->gallery as $image) <img src="{{ $image->web_url }}" alt="Gallery image"> @endforeach
Artisan commands
The Shazzoo Media plugin uses some artisan commands.
Commands | Tags | Uses |
---|---|---|
media:clear |
- | Clears your image files from the storage folder. |
media:conversions:clear-db |
id |
Clears conversion(s) in the database. |
media:conversions:set-db |
id append |
Sets conversion(s) in the databse. |
media:conversions:generate |
id all only |
Generates the conversions for the images. |
media:conversions:regenerate |
id only |
Regenerates the conversions for the images. |
media:conversions:list |
- | Lists out all image conversions |
Policies & Tenancy
Policies
The Shazzoo Media library doesn't use a policy by default but lets you publish a policy template.
php artisan vendor:publish --tag=shazzoo-media-policy
This will publish a policy file to App/Policies/MediaPolicy.php
the policy should be registered automatically by the plugin. The published file will be a blank policy, you will need to add your own rules. Also make sure that media_policies
is set to true in the config/shazzoo_media.php
.
Tenancy
This package does not implement tenancy or user-based access control out of the box.
If your application requires scoping media by tenant, team, or user, you are responsible for applying your own global scope to the ShazzooMedia
model. This can be done by publishing the model and implementing it there, or you can add the global scope in the AppServiceProvider.php
's boot function.