- How do I install awcodes/filament-curator in a Laravel Filament project?
- Install the package with composer require awcodes/filament-curator, then run php artisan curator:install. The install command publishes the config and runs php artisan curator:token to write a CURATOR_GLIDE_TOKEN into your .env file. You also need to add the plugin's theme integration and set the CURATOR_GLIDE_TOKEN key in .env.example and on every environment you deploy to. No database migrations are required unless you customize the Media model.
- Which Filament versions does Filament Curator support?
- Curator tracks Filament's major versions closely: package 1.x and 2.x target Filament 2.x, 3.x targets Filament 3.x, 4.x targets Filament 4.x, and 5.x supports both Filament 4.x and 5.x. Check the compatibility table in the README before upgrading either package. Major Filament releases can introduce breaking changes, so review UPGRADE.md and run php artisan curator:upgrade when moving between supported versions.
- Does Filament Curator work with Spatie Media Library?
- No. The package explicitly does not work with Spatie Media Library, and the README carries a warning to that effect. Curator provides its own Filament-native media model, storage handling, and relationships, so running both in the same project would conflict. If you already use Spatie Media Library, plan a migration that copies existing files to the new disk or directory and updates your model relationships.
- How does Filament Curator handle image resizing and transformations?
- Curator uses Glide to process images on demand, so resizing and cropping happen when a URL is requested rather than through pre-generated variants. Each image can have its own curations, letting you define per-image transformations instead of a single global set. Because processing is lazy, it reduces server load and storage duplication, but you should configure Glide caching appropriately for your deployment, especially behind a CDN.
- What is CURATOR_GLIDE_TOKEN and why is my media route failing or returning an error?
- Curator signs the image URLs it renders with CURATOR_GLIDE_TOKEN, and the media route rejects any request whose signature does not match. The install command generates the token only on the machine where you ran it, so every other environment, including teammates, CI, staging, and production, needs its own value set in .env. If the variable is missing, both generating a media URL and serving the media route will fail. Re-running php artisan curator:token overwrites the existing value, which invalidates previously signed URLs such as cached HTML or URLs already sent in emails.
- Can I use Filament Curator with S3 or other cloud storage?
- Yes. Curator is storage agnostic and works with Laravel's filesystem disks, including local storage and S3-style cloud providers, but you must explicitly configure the disk and directory in config/curator.php. Signed Glide URLs are enabled by default for cloud storage, which can affect performance if overused. For heavier or public workloads, you can register a custom Glide server configuration through a service provider.
- How do I attach media to Eloquent models with Filament Curator?
- Curator provides Filament form fields, such as a media picker, that store single or multiple media relationships on your models. Single relationships suit cases like a post's featured image, while multiple relationships cover galleries such as product images. Eager load the media relationship in your queries to avoid N+1 issues when rendering lists or tables.
- Can I embed Curator media inside Filament's RichEditor?
- Yes. Curator ships a RichEditor plugin so editors can pick and embed media directly in WYSIWYG content without writing custom JavaScript. Register the plugin on the RichEditor field in your Filament resource. Because the resulting URLs are signed, be aware that re-running the token command can invalidate media links embedded in stored content.
- How do I customize the storage path, disk, or fallback images for Curator media?
- Most options live in config/curator.php, where you set the disk, directory, and related behavior. For advanced needs, such as per-user directories, register a custom path generator through a service provider or extend the Media model. Fallback or placeholder images for missing media should be managed by your application and mapped through your own field or accessor logic.
- How do I upgrade Filament Curator between major versions?
- Review UPGRADE.md for the target version and run php artisan curator:upgrade to apply the package's upgrade steps. Confirm your Filament version matches the compatibility table before updating, since major Filament releases can require manual changes. If you are also migrating away from Spatie Media Library, copy the existing files to the new disk or directory first and then update the related model records.