Slider Laravel Package

Getting Started

1. Install and let discovery do its job. composer require mrshanebarron/slider — on Laravel 5.5+ the service provider is auto-registered. Only touch config/app.php if you're on an old skeleton or need to reorder providers.
2. Publish everything in one deliberate pass, using the package's tags rather than a bare vendor:publish (which will drag in unrelated vendor files):

   php artisan vendor:publish --tag=sb-config
   php artisan vendor:publish --tag=sb-assets
   php artisan vendor:publish --tag=sb-views   # only if you intend to override markup
   

   Check the package README for the exact tag names before running — the sb- prefix applies to the config file, and tags usually follow suit.
3. Read the published config top to bottom. For a slider package this is where dimensions, autoplay interval, transition speed, navigation/pagination toggles, and the storage disk live. It is the real documentation; every env() the package reads is in there, so it doubles as your .env.example checklist.
4. Set up storage. Slider images are almost always disk-backed: confirm the disk name in config, run php artisan storage:link if it's the public disk, and verify with a hardcoded path before wiring uploads.
5. Resolve the slides table. If the package ships migrations, publish and run them (--tag=sb-migrations then php artisan migrate). If not, you own the schema — create the model/table yourself and match the column names the package's renderer expects (image, title, caption, link, sort/position, visibility flag). Getting these column names right on day one prevents the most common "slider renders empty" report.

First use case: seed two or three rows, drop the package's Blade component/include into one existing layout, and confirm images render in the right order. That single end-to-end path proves the config, the disk, the schema, and the asset publish are all correct — in that order of likelihood of being wrong.

Implementation Patterns

Group your sliders from day one. A hero banner and a sidebar carousel are different content, and retrofitting a group/key column later means a data migration. Add it to the table before you have real content, then render with the group as an argument.

Ordering is a write-path problem, not a read-path one. Store an integer sort column with a unique-per-group index, and implement drag-reorder as a single transactional batch update (lockForUpdate, then rewrite positions 1..n). Do not let admins type arbitrary numbers into a text field — you'll get duplicates and gaps that make the read query ambiguous. Read with orderBy('sort') and keep the tiebreaker explicit (->orderBy('id')) so results are deterministic in tests.

Scope visibility in the model, not the view. Put active() and scheduled() (published_at window) scopes on the slide model and always start the slider query from them. Views should never contain @if ($slide->is_active) — that's how inactive slides leak into production.

Cache the query, bust it on write. Sliders render on the highest-traffic page in the app, which makes them a prime N+1/cache target. Cache::remember("slider.{$group}", ...) around the collection, and forget it from a model saved/deleted observer plus on reorder. Key the cache on the group, not the route — the same slider usually appears in several places.

Isolate the frontend asset. Published vendor JS is global by default. Wrap script inclusion in @once (or @push('scripts')) so it only loads on pages that actually render a slider, and pin the published asset filename in your deploy so a re-publish doesn't silently swap versions under a browser cache.

Make images render-ready at upload time. Store one canonical upload and generate the exact dimensions the config expects (plus a 2x), rather than letting the Blade view scale a 4000px JPEG. This is also where you enforce alt text — see gotchas.

Testing. Use RefreshDatabase and a slide factory; assert the rendered HTML contains images in the expected order and that inactive slides are absent. Override slider options with config(['sb-slider.autoplay' => false]) inside the test rather than editing the config file.

Deployment order: composer install → publish/migrate (first deploy only) → php artisan storage:link (first deploy only) → php artisan view:clear if you've overridden views → php artisan config:cache last.

Gotchas and Tips

• The sb- prefix is a moving target. v1.0.1 only fixed the config filename. If you installed earlier, your published file still has the old name, and Laravel won't overwrite it without --force. After upgrading, run ls config | grep sb- and confirm exactly one slider config exists — a stale duplicate means mergeConfigFrom() silently wins with defaults.
• --force clobbers customisations. Before re-publishing to pick up new config keys, copy config/sb-slider.php aside or diff it against vendor/mrshanebarron/slider/config/. The same applies to published views and assets.
• Silent empties are the signature failure mode. A missing slide row, a wrong column name, or an unlinked storage disk typically produces an empty slider rather than an exception. Add a one-line guard (throw on empty in local, log-with-context elsewhere) so misconfiguration surfaces at deploy time.
• Timing units are the classic config quirk. Autoplay intervals in slider packages are frequently milliseconds while everyone's mental model is seconds — a 5 that means 5ms produces an unusable flicker. Read the config's comments before setting a value, and test on a real page, not in a unit test.
• Multiple instances on one page collide. If the underlying JS initialises by class or global ID, two sliders on a page will fight (double timers, wrong pagination). Scope initialisation to a container element and give each instance a unique key.
• Cache-busted config, not cache-busted assets. php artisan config:clear after any .env change locally; on production always finish with config:cache again. And never call env() in your own providers or view composers — it returns null under cached config.
• Layout shift from unsized images. If the config sets responsive dimensions, emit width/height (or an aspect-ratio wrapper) on the image tag; otherwise the slider causes a CLS hit on your best-performing page.
• Accessibility is your job, not the package's. Require alt text at the model/admin layer, ensure the slider doesn't autoplay under prefers-reduced-motion, and verify arrow controls are keyboard-focusable. Vendor sliders rarely ship this and audits will find it.
• Soft deletes vs. visibility flags. If the model uses SoftDeletes, a "deleted" slide disappears from the admin list but may still satisfy your active() scope depending on whether the global scope is applied in the package's query. Check the SQL with ->toSql() once rather than guessing.
• Pin the version. With the config naming only just stabilised, "^1.0" is sensible; avoid * until you've seen a minor release land without a filename or key change.