Filament Carousels Laravel Package

Getting Started

1. Install the package and publish its assets:

   composer require rectitude-open/filament-carousels
   php artisan vendor:publish --tag="filament-carousels-config"
   php artisan vendor:publish --tag="filament-carousels-migrations"
   php artisan migrate
   

2. Register the plugin on each Filament panel you want it in:

   use RectitudeOpen\FilamentCarousels\FilamentCarouselsPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           // ...
           ->plugin(FilamentCarouselsPlugin::make());
   }
   

3. Look here first:

   • config/filament-carousels.php — media model, upload disk, image conversions, and other knobs.
   • The published migrations — they define the carousels, categories, and picture/media tables and their foreign keys.
   • CarouselResource (and its pages) — this is the admin surface you will customize most often.

4. First use case: create a Carousel in the Filament admin, optionally assign it a Category, add Carousel Items with images, then render the carousel on the front end by fetching the carousel via its model and iterating its ordered items/pictures. Confirm the storage:link exists before uploading images so the admin previews render.

Implementation Patterns

• Config-driven media model. Point filament-carousels.media_model (or the equivalent key) at your application's media/image model. As of v1.2.1 the pictures relationship resolves the model from config, so you can swap in a custom model without forking the package.

• Panel-scoped registration. Register the plugin only on the panels that should expose carousel management (e.g. an admin panel), keeping editor-facing panels lean.

• Resource extension. Subclass or reconfigure the provided CarouselResource/CarouselItemResource to add fields (alt text, links, scheduling, translations) rather than editing vendor files. Use Filament's ->form() / ->table() overrides on the resource or a custom resource that extends the package one.

• Front-end rendering. Query the model directly in a controller, view composer, or Blade component:

  $carousel = Carousel::where('slug', 'homepage')
      ->with(['items.pictures'])
      ->firstOrFail();
  

  Eager-load items and pictures to avoid N+1 queries; the package's relationships are the supported integration point.

• Categories as a grouping layer. Use categories for placement (homepage, sidebar, campaign) and keep carousels keyed by slug so templates stay stable while editors rearrange content.

• Seeding and fixtures. Seed carousels/items in tests and local setups; because the media model is configurable, seed against the configured model to keep environments consistent.

• Blade/component wrapper. Wrap the front-end loop in a small Blade component (<x-carousel :carousel="$carousel" />) so markup and image conversion handling live in one place.

Gotchas and Tips

• Re-publish config after upgrades when in doubt, and always clear config cache (php artisan config:clear) after changing the media model — Filament and Laravel both cache aggressively, and a stale media_model produces confusing "class not found" or relationship errors.
• The v1.2.1 category-table fix matters if you renamed or schema-qualified the category table. The category query now specifies the table name explicitly; if you have a non-standard category table (or a joined query with an id/name collision), retest category filtering after upgrading.
• Media model contract. Whatever you set as the media model must be a real Eloquent model wired to the expected media table and supporting the relationship the package expects. Check the migrations before pointing it at an existing model.
• Storage and URLs. Missing php artisan storage:link or a misconfigured disk is the most common "images don't show" cause. Verify the upload disk in config matches the disk you serve from.
• Ordering is editor-driven. If your front end depends on item order, add an explicit sort column/field and order the relationship query rather than relying on insertion order.
• Filament version compatibility. This is a Filament plugin; pin a compatible Filament major version in composer.json and run composer update --with-dependencies deliberately, since plugin releases track Filament internals.
• Upgrade hygiene for patch releases. v1.2.1 is a pure bug-fix patch (no breaking changes), so a routine composer update rectitude-open/filament-carousels followed by php artisan migrate (if any new migrations appear) and a config cache clear is sufficient. Review the diff if you have customized the category query or media relationship.
• Extension points to prefer: config for media model/disk, subclassed resources for admin fields, and model relationships for front-end queries. Avoid editing package source directly so future patch releases (like this one) apply cleanly.