• Stars
    star
    321
  • Rank 130,752 (Top 3 %)
  • Language
    PHP
  • License
    MIT License
  • Created over 2 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A media picker plugin for Filament Panels.

Filament Curator

Latest Version on Packagist Total Downloads

A media picker/manager plugin for Filament Admin.

Warning This package does not work with Spatie Media Library.

Warning If you are using the Curator integration with Filament Tiptap Editor you will also need to update it to version 2.3.0 or higher.

curator-og

Installation

You can install the package via composer then run the installation command:

composer require awcodes/filament-curator
php artisan curator:install

Upgrading

If you are upgrading from 1.x to 2.x you will also need to run:

php artisan curator:upgrade

This will update Curator's database schema and create a backup of your media table that can be deleted after upgrade should you choose to do so.

Additional Steps

  1. Change any references in your codebase from $media->filename to $media->path.
  2. Change any use statements from FilamentCurator to Awcodes\Curator.
  3. Change FilamentCurator\Forms\Components\MediaPicker fields to Awcodes\Curator\Components\Forms\CuratorPicker.

Usage

Global Settings

Global settings for Curator are handled through the Curator facade. Inside the register() method of a service provider you can customize the behaviour of Curator's resources. All methods are optional.

use Awcodes\Curator\Facades\Curator;

public function register()
{
    Curator::disableResourceRegistration()
        ->resourceLabel(string|Closure)
        ->pluralResourceLabel(string|Closure)
        ->navigationIcon(string)
        ->navigationSort(int)
        ->navigationGroup(string)
        ->registerNavigation(bool|Closure|null)
        ->tableHasIconActions(bool|Closure|null)
        ->tableHasGridLayout(bool|Closure|null)
        ->curationPresets(array|null)        
        ->gliderFallbacks(array|null)
        ->preserveFilenames(bool|Closure)
        ->acceptedFileTypes(array|Closure)
        ->maxWidth(int|Closure)
        ->minSize(int|Closure)
        ->maxSize(int|Closure)
        ->disk(string|Closure)
        ->directory(string|Closure)
        ->pathGenerator(string|null)
        ->visibility(string|Closure)
        ->cloudDisks(array)
        ->imageCropAspectRatio(string|Closure|null)
        ->imageResizeTargetHeight(string|Closure|null)
        ->imageResizeTargetWidth(string|Closure|null)
        ->glideSourcePathPrefix(string)
        ->glideCachePathPrefix(string)
        ->glideServer(Server|ServerFactory)
        ->glideMaxImageSize(int)
        ->glideDriver(string)
        ->mediaModel(string);
}

Curator Picker Field

Include the CuratorPicker field in your forms to trigger the modal and either select an existing image or upload a new one. Some common methods from Filament's FileUpload component can be used to help with sizing, validation, etc. for specific instances of each CuratorPicker.

use Awcodes\Curator\Components\Forms\CuratorPicker;

CuratorPicker::make(string $fieldName)
    ->label(string $customLabel)
    ->buttonLabel(string | Htmlable | Closure $buttonLabel)
    ->color('primary|secondary|success|danger') // defaults to primary
    ->outlined(true|false) // defaults to true
    ->size('sm|md|lg') // defaults to md
    ->constrained(true|false) // defaults to false (forces image to fit inside 
    the preview area)
    ->pathGenerator(DatePathGenerator::class|UserPathGenerator::class) // see path generators below
    // see https://filamentphp.com/docs/2.x/forms/fields#file-upload for more information about the following methods
    ->preserveFilenames()
    ->maxWidth()
    ->minSize()
    ->maxSize()
    ->rules()
    ->acceptedFileTypes()
    ->disk()
    ->visibility()
    ->directory()
    ->imageCropAspectRatio()
    ->imageResizeTargetWidth()
    ->imageResizeTargetHeight()
    ->multiple() // required if using a relationship with multiple media
    ->relationship(string $relationshipName, string 'titleColumnName')

Relationships

Single

Form component

CuratorPicker::make('featured_image_id')
    ->relationship('featured_image', 'id'),

Model

use Awcodes\Curator\Models\Media;

public function featuredImage(): BelongsTo
{
    return $this->belongsTo(Media::class, 'featured_image_id', 'id');
}

Multiple

Form component

CuratorPicker::make('product_picture_ids')
    ->multiple()
    ->relationship('product_pictures', 'id'),

Model

use Awcodes\Curator\Models\Media;

public function productPictures(): BelongsTo
{
    return $this->belongsToMany(Media::class, 'media_post', 'post_id', 'media_id');
}

Path Generation

By default, Curator will use the directory and disk set in the config to store your media. If you'd like to store the media in a different way Curator comes with Path Generators that can be used to modify the behavior. Just set the one you want to use the register() method of a service provider.

public function register()
{
    Curator::pathGenerator(DatePathGenerator::class);
}

Available Generators

DefaultPathGenerator will save files in disk/directory.

DatePathGenerator will save files in disk/directory/Y/m/d.

UserPathGenerator will save files in disk/directory/user-auth-identifier

You are also free to use your own Path Generators by implementing the PathGenerator interface on your own classes.

use Awcodes\Curator\Generators;

class CustomPathGenerator implements PathGenerator
{
    public function getPath(?string $baseDir = null): string
    {
        return ($baseDir ? $baseDir . '/' : '') . 'my/custom/path';
    }
}

Path Generators can also be passed into the directory() method on the CuratorPicker field for per instance use.

CuratorPicker::make(string $fieldName)
    ->label(string $customLabel)
    ->pathGenerator(CustomPathGenerator::class),

Curator Column

To render your media in a table Curator comes with a CuratorColumn which has the same methods as Filament's ImageColumn.

CuratorColumn::make('featured_image')
    ->size(40)

For multiple images you can control the number of images shown, the ring size and the overlap.

CuratorColumn::make('product_pictures')
    ->ring(2) // options 0,1,2,4
    ->overlap(4) // options 0,2,3,4
    ->limit(3),

Relationships

If you are using a relationship to store your media then you will encounter n+1 issues on the column. In order to prevent this you should modify your table query to eager load the relationship.

For example when using the admin panel in your ListResource

protected function getTableQuery(): Builder
{
    return parent::getTableQuery()->with(['featured_image', 'product_pictures']);
}

Curations

Curations are a way to create custom sizes and focal points for your images.

Curation Presets

If you have a curation that you are constantly using you can create Presets which will be available in the Curation modal for easier reuse. After creating curation presets, they can be referenced by their key to output them in your blade files.

use Awcodes\Curator\CurationPreset;

Curator::curationPresets([
    CurationPreset::make('thumbnail')
        ->label('Thumbnail')
        ->width(200)
        ->height(200)
        ->format('webp')
        ->quality(80),
    CurationPreset::make('hero')
        ->label('Hero')
        ->width(960)
        ->height(300),
    CurationPreset::make(name: 'og-image')
        ->label('OG Image')
        ->width(1200)
        ->height(630),
]);

Glider Blade Component

To make it as easy as possible to output your media, Curator comes with an <x-curator-glider> blade component.

See Glide's quick reference for more information about Glide's options.

Special attributes

  • media: id (int) or model (Media) instance required
  • loading: defaults to 'lazy'
  • glide: this can be used to pass in a glide query string if you do not want to use individual attributes
  • srcset: this will output the necessary srcset with glide generated urls. Must be an array of srcset widths and requires the 'sizes' attribute to also be set.
<div class="aspect-video w-64">
    <x-curator-glider
        class="object-cover w-auto"
        :media="1"
        glide=""
        fallback=""
        :srcset="['1024w','640w']"
        sizes="(max-width: 1200px) 100vw, 1024px"
        background=""
        blur=""
        border=""
        brightness=""
        contrast=""
        crop=""
        device-pixel-ratio=""
        filter=""
        fit=""
        flip=""
        format=""
        gamma=""
        height=""
        quality=""
        orientation=""
        pixelate=""
        sharpen=""
        width=""
        watermark-path=""
        watermark-width=""
        watermark-height=""
        watermark-x-offset=""
        watermark-y-offset=""
        watermark-padding=""
        watermark-position=""
        watermark-alpha=""
    />
</div>

Fallback Images

Glider allows for a fallback image to be used if the media item does not exist. This can be set by passing in the fallback attribute referencing one of your registered GliderFallbacks.

use Awcodes\Curator\GliderFallback;

Curator::gliderFallbacks([
    GliderFallback::make(key: 'thumbnail')
        ->source('defaults/thumbnail.jpg')
        ->alt('party at LaraconIN')
        ->width(200)
        ->height(200),
]);
<x-curator-glider :media="1" fallback="thumbnail" />

Curation Blade Component

To make it as easy as possible to output your curations, Curator comes with an <x-curator-curation> blade component.

Special attributes

  • media: id (int) or model (Media) instance required
<x-curator-curation :media="10" curation="thumbnail" loading="lazy" />

Practical use case

Since curations may or may not exist for each media item it's good to use a fallback to the glider component in your blade file so images always get rendered appropriately. This also keeps you from having to create curations for every media item, only the ones where you're trying to change the focal point, etc.

@if ($media->hasCuration('thumbnail'))
    <x-curator-curation :media="$media" curation="thumbnail" />
@else
    <x-curator-glider
        class="object-cover w-auto"
        :media="$media"
        :width="curator()->preset('thumbnail')['width']"
        :height="curator()->preset('thumbnail')['height']"
    />
@endif

Custom Resource

Should you need to override the default Resources, it is recommended that you use the service container to bind Curator's Resource name to your own extensions of them.

use Awcodes\Curator\Resources\MediaResource;
use Awcodes\Curator\Facades\Curator;

class YourNotAsCoolMediaResource extends MediaResource
{
    // ... custom methods and properties
}

class YourNotAsCoolEditMedia extends MediaResource\EditMedia
{
    // ... custom methods and properties
}

class YourNotAsCoolCreateMedia extends MediaResource\CreateMedia
{
    // ... custom methods and properties
}

class YourNotAsCoolListMedia extends MediaResource\ListMedia
{
    // ... custom methods and properties
}

// and in a service provider
public function register()
{
    Curator::disableResourceRegistration();
    $this->app->bind(MediaResource::class, fn() => new YourNotAsCoolMediaResource());
    $this->app->bind(MediaResource\EditMedia::class, fn() => new YourNotAsCoolEditMedia());
    $this->app->bind(MediaResource\CreateMedia::class, fn() => new YourNotAsCoolCreateMedia());
    $this->app->bind(MediaResource\ListMedia::class, fn() => new YourNotAsCoolListMedia());
}

Theming

If you are using a custom theme for Filament you will need to add this plugin's views to your tailwind.config.js.

content: [
    ...
    "./vendor/awcodes/curator/resources/views/**/*.blade.php",
]

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

More Repositories

1

filament-tiptap-editor

A Rich Text Editor plugin for Filament Forms.
PHP
275
star
2

filament-table-repeater

A modified version of the Filament Forms Repeater to display it as a table.
PHP
199
star
3

filament-quick-create

Plugin for Filament Panels that adds a dropdown menu to the header to quickly create new items.
PHP
165
star
4

overlook

An app overview widget for Filament panels.
PHP
158
star
5

filament-badgeable-column

A custom table column that supports prefixed and suffixed badges to the column content.
PHP
118
star
6

drop-in-action

A form component for Filamentphp allowing actions inside of forms.
PHP
86
star
7

alpine-floating-ui

Add Floating UI functionality to Alpine 3.x components.
JavaScript
79
star
8

filament-sticky-header

A Filament Panels plugin to make headers sticky when scrolling.
PHP
60
star
9

shout

A simple inline contextual notice for Filament forms, basically just a fancy placeholder.
PHP
50
star
10

scribble

PHP
43
star
11

filament-versions

A mostly useless package to display framework versions on Filament panels.
PHP
40
star
12

filament-addons

A set of components / fields to extend Filament Admin.
PHP
30
star
13

light-switch

Plugin to add theme switching (light/dark/system) to the auth pages for Filament Panels.
PHP
29
star
14

filament-extras

PHP
28
star
15

filament-gravatar

Replace Filament's default avatar url provider with one for Gravatar.
PHP
26
star
16

recently

Easily track and access recently viewed records in your filament panels.
PHP
22
star
17

repro

CLI tool for quickly recreating reproduction repos locally.
PHP
18
star
18

preset-color-picker

A color picker field for Filament Forms that uses preset color palettes.
PHP
17
star
19

Matinee

OEmbed field for Filament Panel and Form Builders.
PHP
17
star
20

filament-installer

Filament Admin Panel application installer.
PHP
16
star
21

html-faker

A better html faker.
PHP
13
star
22

trov

A Laravel / Filament starter kit for CMS functionality on websites.
PHP
11
star
23

hydro

CLI for creating new Filament plugins
PHP
9
star
24

filament-plugin-purge

A purge tool to keep your Filament plugin from bloating / duplicating Filament's default styles.
CSS
9
star
25

palette

A color picker field for Filament Forms that uses preset color palettes.
PHP
8
star
26

pounce

A global modal/dialog plugin for Filament.
PHP
7
star
27

filament-sentry

A basic auth scaffolding for Filament utilizing Filament Breezy, Filament Shield and custom User Resources.
PHP
7
star
28

filament-oembed

PHP
6
star
29

sink

A collection of components for Filament.
PHP
6
star
30

curator

PHP
4
star
31

translation-field

A form component for Filament to handle translations at the field / input level.
PHP
3
star
32

postal-codes

This is a package to easily install and use postal codes in your Laravel application from GeoNames.org
PHP
3
star
33

tiptap-demo

Project for testing tiptap functionality
PHP
3
star
34

assistant

A collection of helpers for use in Laravel projects.
PHP
2
star
35

dimmer

Blade
2
star
36

trov-components

A set of components, fields and layouts to extend Filament Admin.
PHP
2
star
37

awcodes-astro

Astro
2
star
38

filament-skins

PHP
2
star
39

gtm

Easy integration of Google Tag Manager into your Laravel application.
PHP
2
star
40

trov-installer

PHP
1
star
41

colors-experiment

PHP
1
star
42

pluginshot

AWcodes Plugin Screenshot Generator
PHP
1
star
43

headings

A Custom Form Component to demo building a standalone Forms Builder plugin for Filament
PHP
1
star
44

laravel-remix

Revert a new Laravel application to Laravel Mix.
PHP
1
star
45

trov-filament

PHP
1
star