How awcodes/filament-curator works
Project Type and Purpose
• Type: A Laravel “plugin” package (PHP library) that integrates into Filament Admin panels or stand-alone Filament Forms to provide a media picker/manager.
• Purpose: Let developers embed a modal/UI for selecting, uploading, curating, and serving images via Glide (on-the-fly image manipulation).
File Structure
• Top-level:
– src/ → core PHP code (ServiceProvider, Controllers, Models, Actions, Components, Concerns, Observers, PathGenerators, Glide integration, Curations).
– resources/ → Blade views (modals, components), JavaScript/CSS builds, translation files.
– config/curator.php → global settings.
– database/migrations & factories → media table schema.
– bin/build.js, package.json, tailwind.config.js, postcss.config.cjs → front-end asset build pipeline.
– routes/web.php → Glide/image-serving route.
• Patterns:
– MVC (MediaController, Media model, Blade views).
– Service provider pattern (CuratorServiceProvider).
– Observer pattern (MediaObserver).
– Strategy pattern for path generation (PathGenerator interface) and for Glide server (ServerFactory).
Key Insights from README
• Installs via Composer; registers artisan commands (curator:install, curator:upgrade).
• Requires a custom Filament theme + Cropper.js → CSS/JS assets loaded into Filament.
• Exposes Blade components: <x-curator-picker>, <x-curator-glider>, <x-curator-curation>.
• Uses league/glide for dynamic image URLs and presets for curation.
Main Components & Their Relationships
A. Host Laravel Application (outermost context)
• ServiceProvider Registration → loads config, publishes assets, migrations, registers Glide route & Filament plugin.
• Artisan Commands → build assets, run migrations.
B. Filament Admin / Filament Forms UI
• Blade views & Components (resources/views, src/View/Components)
• CuratorPicker field (JS/Cropper.js + plugin.css)
• Modals (upload & curation UI)
→ HTTP requests (AJAX/form submits) → MediaController
C. Backend Processing
• src/Http/Controllers/MediaController.php (handles uploads, CRUD)
• src/Actions (MediaAction, MultiUploadAction) – encapsulate upload logic
• src/Models/Media.php – Eloquent model mapped to media table
• src/Observers/MediaObserver.php – hooks on model events (e.g., generate thumbnails, remove files)
• src/PathGenerators – determine storage paths
• Storage Disk (Laravel Filesystem) – writes files to disk/cloud
D. Image Serving & Curation
• routes/web.php → Glide route (e.g., /curator)
• src/Glide/GlideBuilder & DefaultServerFactory – configure and return League\Glide Server
• Glide pipeline → reads source image, applies query parameters (resize, crop, filters), outputs response
• Glider Blade component → generates signed Glide URLs, optionally srcset/fallback
E. Persistence
• Database (media table + potential pivot tables for morph/many relationships)
• Migrations (database/migrations)
F. Front-end Build Tooling
• bin/build.js, package.json, tailwind.config.js, postcss.config.cjs
• Outputs plugin.css, curator.js, curation.js in resources/dist
Architectural Patterns & Design Principles
• Modular design: clear separation between UI (Blade/JS/CSS), domain logic (Actions, Models), and infrastructure (Storage, Glide).
• Dependency Injection: ServiceProvider binds interfaces (ServerFactory, PathGenerator).
• Open/Closed: PathGenerators and GliderFallbacks are pluggable by implementing provided interfaces.
• Observer: Post-upload hooks for additional processing.
Technologies & Frameworks (label these
• PHP 8+, Laravel Framework, Filament Admin package
• Composer for PHP dependencies
• Blade components, Eloquent ORM, Laravel Filesystem
• League\Glide for image processing
• Cropper.js, Tailwind CSS, PostCSS for front-end
• Pest/PhpUnit for tests
– UI (blue): Blade views, JS/CSS, Cropper.js
– Backend Logic (green): Controllers, Actions, Observers, ServiceProvider
– Data (orange): Eloquent Models, Migrations, Database, Storage Disk
– External/3rd-party (gray): Filament Admin, League\Glide, Laravel Framework