Visual Debut Laravel Package

Getting Started

Close the compatibility matrix before writing code. Four axes decide whether this package is usable at all: PHP version, Laravel version, Bagisto version, and the session/cache driver pairing. The repository ships no documented matrix, so establish it empirically on a disposable storefront copy. If the front end is headless or SPA-based, stop — the value here is server-rendered Blade, and almost nothing transfers.

Pin the exact alpha. Do not use a caret constraint. Add the exact version so a silent alpha bump cannot break the event contract or override your views:

composer require bagistoplus/visual-debut:2.0.0-alpha.12 --with-all-dependencies

An exact version constraint avoids setting minimum-stability: alpha globally, which would otherwise loosen the whole dependency graph.

Where to look first, in order:

1. composer.json — check the illuminate/* and bagisto/* constraints directly; treat them as the real compatibility statement.
2. The service provider in src/ — what it registers, publishes, and merges. This tells you whether configuration is the extension model or whether you are expected to override views.
3. resources/views/ — the Blade component tree. This is where the header cart, flash messages, variant picker, wishlist, and compare markup live.
4. resources/js/ and vite.config.* — how the JS side binds to cart/wishlist/compare updates. Confirm Vite vs Mix and the CSS framework before scoping any styling work.
5. config/ — the configurable toggles referenced in the package description.
6. routes/ — any AJAX endpoints used to hydrate per-shopper fragments (this is likely how the alpha.12 cache fix works).

Publish config and assets using the provider name you found in step 2; the namespace is not documented, so read the provider class rather than guessing.

First use case: one template, not the whole storefront. Port a single low-traffic template end to end — a category listing or a static content page — and confirm the theme's layout, asset pipeline, and slot/override mechanics work in your stack. Do this before touching cart or PDP. It produces a real migration estimate instead of a guess and surfaces asset-bundler mismatches cheaply.

First functional smoke test — the two shipped fixes. Reproduce the exact scenarios the alpha.12 changelog names:

# Terminal A
curl -c jarA -b jarA https://shop.test/  # warm the full-page cache, add to cart
# Terminal B
curl -c jarB -b jarB https://shop.test/  # assert no cart count / flash bleed from A

Then on the PDP: select a variant, add to cart, and assert the cart line matches the variant picker selection. These two flows are the package's current quality frontier and the fastest way to learn whether you are looking at a working install.

Implementation Patterns

Override views, don't fork. Laravel's resources/views/vendor/{package}/... precedence is almost certainly the intended extension seam. Keep every customization in your app's view tree, keyed to the same relative paths, so an upstream alpha bump produces a diff you can read instead of a merge conflict you cannot. Fork only if you need to change the service provider's registration or the fragment-hydration logic.

Compose through layouts and slots. The package advertises "Blade-friendly components for custom layouts" — use @push/@stack for scripts and styles and the theme's section/include structure for content, rather than editing theme partials in place. This keeps your deltas small and makes the eventual GA migration a re-apply rather than a rewrite.

Treat the dispatched events as your integration boundary. The package emits compare updated and wishlist updated events, alongside existing cart events. This is the cheapest place to hang analytics, saved-item campaigns, recommendation triggers, and abandonment signals without touching theme code. Pattern:

1. Write a throwaway listener that Log::info()s the event class, payload shape, and dispatch timing for every event you care about.
2. Run each flow manually once and capture actual payloads. Do not trust names in the changelog to imply payload shape.
3. Turn those captures into contract tests — assert the event fires with the expected keys. These are your early-warning system for an alpha bump that silently renames something.
4. Only then write real listeners.

Register listeners in your own provider, not the theme's. Keeps the hooks alive through package upgrades and makes them easy to disable.

Render per-shopper fragments outside the cache. The alpha.12 fix for header cart and flash messages under full-page cache implies the theme now handles shopper-specific fragments correctly — but it also implies you can break that handling by how you wire your own fragments. Convention to adopt: any state that varies by shopper (cart count, cart contents, flash messages, wishlist, compare counts) is either rendered through the theme's fragment mechanism or hydrated after page load by AJAX. Never interpolated into a page-cacheable response.

Variant picker: dispatch and listen on the same cart-updated event the theme uses. The alpha.12 fix "listen for the correct cart updated event in the variant picker" means the theme standardizes on one event name for this. If you build or customize a variant widget, listen to and dispatch that same event — a near-miss name produces a picker that looks fine and adds the wrong line to the cart.

Integration sequence that survives an alpha:

1. Pin alpha.12 on a sandbox branch.
2. Behaviour-diff all five flows (cart count, cart contents, flash messages, variant selection, wishlist, compare) against your current storefront.
3. Capture the event contract.
4. Port one template.
5. Only then estimate the full port, with a second migration budgeted for GA.

Wrap the theme's public surface. If your own controllers or Blade components call into theme internals, put a thin adapter in your app code. When the alpha changes an internal, you edit one file instead of grepping the whole app.

Gotchas and Tips

The marketplace description is wrong — scope from the code. It describes a lightweight "visual debut" layer with "no heavy dependencies." The changelog and the feature set show a full storefront theme that owns header cart, flash messaging, variant selection, wishlist, and compare, and that interacts with full-page cache. Anyone estimating from the description will under-scope by multiples.

Cache correctness is a launch gate, not a bug ticket. The alpha.12 fix is for per-shopper header cart and flash messages leaking under full-page cache. That is a cross-shopper data-exposure class of defect. Before anything resembling production:

• Two concurrent simulated shoppers, a warmed cache, interleaved requests.
• Assert zero bleed of cart count, cart contents, flash messages, wishlist, or compare state.
• Repeat on every cache driver you actually run — Redis, file, and CDN edge behave differently, and the fix may not be driver-agnostic.
• Repeat with the session driver you actually run. cookie sessions and full-page cache are a combination to be suspicious of by default.

Pin, then pin again. Twelve alphas reads as churn. Semver permits breaking changes on the event names, payloads, view paths, and config keys. Use an exact constraint, name an owner for upgrade reviews, and re-run the contract tests on every bump.

Silent event breakage is the most likely failure mode. If wishlist updated or compare updated is renamed before GA, downstream listeners simply stop firing — no exception, no 500, just missing analytics and dead personalization. Contract tests are the only cheap detection. Add a canary: a listener whose only job is to increment a metric on each event so a drop is visible.

Variant-picker desync produces wrong-item orders, which is revenue-visible. The alpha.12 fix sits directly on the add-to-cart path. Add an order-audit sample: pull recent orders and confirm the variant recorded matches what the picker would have selected. Cheap, and it catches what unit tests miss.

Debugging checklist when a fragment looks stale or wrong:

php artisan view:clear
php artisan route:list | grep -i visual
php artisan event:list | grep -iE 'cart|wishlist|compare'
php artisan config:show cache
php artisan config:show session

If the header cart count is wrong but the cart page is right, the problem is fragment hydration or cache isolation, not business logic. If the event list is missing names, your listener provider is not registered or is registered after the theme's.

Provider registration order matters. If the theme rebinds or replaces any cart/session helper, a provider registered ahead of it will see the wrong instance. Register your listeners and overrides after the theme's provider.

There is no external corpus. Two stars, zero dependents, no Stack Overflow history, no troubleshooting knowledge base. Every problem is a source-reading problem. Budget for that: one engineer who has read src/ end to end is worth more than any amount of searching.

Do not do a partial in-place swap on a live theme. Install on a disposable storefront copy, behaviour-diff, then swap. The theme owns enough state surface that a half-migrated storefront can produce plausible-looking pages with incorrect cart lines.

Know the extension points before you need them. In order of preference: config toggles → view overrides → event listeners → fork. If you find yourself extending a theme class directly, you have taken on maintenance the package's alpha cadence will make expensive.

Where this package does nothing for you: checkout, headless/API layers, and design ownership. If your roadmap is SPA-first or needs deep checkout customization, the theme's value largely evaporates and only the event contract survives — which is a much weaker business case than "we bought a theme."