Snipcart Laravel Package

Getting Started

v1.0.0 is the first stable release, and it is effectively a new package compared to the beta line — config, product blueprint, tags and modifiers were all refactored. Budget for a fresh install rather than an in-place upgrade.

1. Install from a clean state — require the package via Composer, publish its config and any assets/migrations, and run migrations. Do not reuse a beta-published config file; the shape has changed.
2. Read the config file first. It is the primary control surface: collection handle, blueprint source, tag definitions and modifier registration all live there now. Anything you previously hardcoded is likely read from config in 1.0.
3. Inspect the shipped product blueprint before writing your own. Compare it field-by-field against your beta blueprint and note renames/removals — this is where most migration pain will come from.
4. Create a brand-new product collection (as the release notes recommend), attach the new blueprint, and manually migrate a handful of products. Validate tags and modifiers render correctly on that small sample before touching production data.
5. First real use case: stand up a second, disposable product collection in a local/staging environment, seed 5–10 products with tags and at least one modifier, and confirm the full render/query path works. That gives you a reference implementation to migrate the rest against.

Implementation Patterns

Config-as-source-of-truth. Keep the published config under version control and drive collection handles, blueprint paths and modifier registrations from it (env-driven where the value differs between environments). Never reference a collection handle literally in application code — resolve it from config so renames don't cascade.

Blueprint as code. Store the product blueprint in the repo and deploy it alongside the config. Treat it like a migration: changes should be reviewed, and you need a deliberate step (re-save, sync command, or a one-off script) to apply field changes to existing products, because existing entries generally don't pick up blueprint edits automatically.

Modifiers as a composable pipeline. Register modifiers in config and keep each one small and side-effect free. Order matters — apply pricing/availability modifiers before presentation modifiers, and be explicit about ordering in the config rather than relying on registration order. If modifiers touch the database or an external API, batch or cache them; a modifier that queries per-product is the most common performance cliff in this kind of addon.

Tags: register, then cache. Define custom tags through the documented extension point rather than editing vendor code. Tag output is usually the expensive part of a page render, so cache the rendered result (or the underlying product lookup) and key the cache on the product collection plus any filter parameters.

Migration script for beta data. Rather than hand-editing, write a one-off artisan command that maps old product fields → new blueprint fields, re-attaches tags, and writes into the new collection. Run it against a staging copy, diff a sample of products, then run in production. Keep the command in the repo (not deleted) so you can re-run in a rollback scenario.

Testing. Give the test suite its own product collection + blueprint fixture and a factory, so tests don't depend on production content. Assert on modifiers and tag output separately — they fail independently.

Deployment. After config or blueprint changes, re-run the config cache and clear the addon's data/index cache as part of the deploy. Wire this into your deploy script; it is the single most common cause of "works locally, broken in staging".

Gotchas and Tips

• There is no automated upgrade path from beta. The release notes are explicit: config, blueprint, tags and modifiers all changed. Don't try to patch a beta install — install clean, build a new collection, migrate data deliberately. This is a breaking release despite the 1.0 version number.
• Product IDs/handles may not survive. Anything outside the addon that stores a product reference (orders, content entries, hardcoded links, an external CRM) needs an audit. Build an old-ID → new-ID mapping table during migration and keep it.
• Blueprint changes are not retroactive. Adding/renaming a field updates the blueprint but leaves existing products without that value. Plan a backfill pass; don't assume null means "field missing" versus "not yet migrated".
• Caches mask breakage. Config cache, Laravel's cache, and any addon-side index/Stache cache can all hold stale definitions. When something looks wrong after a deploy, clear all three before debugging logic. php artisan config:clear and a fresh config:cache after every config edit.
• Modifier ordering is load-bearing. Two modifiers that both mutate price will produce different output depending on registration order. Encode the intended order explicitly and add a test that pins it.
• Modifier N+1. If modifiers or tags resolve relations lazily, a listing page will fire a query per product. Eager-load or pre-resolve in a single pass.
• Tag output escaping. Tag-style output frequently bypasses Blade escaping. If tags emit HTML, ensure escaping is explicit where user-supplied content is involved.
• Extension points to prefer: config-driven registration for modifiers and tags, custom blueprint fields for product-specific data, and events/listeners for reacting to product changes — all survive minor upgrades better than subclassing internals.
• Post-1.0, hold the line on semver. Now that it's stable, pin to ^1.0 and read changelogs for minor releases; the beta-era habit of "just update and fix what breaks" is no longer appropriate for production.
• When stuck, compare against a fresh install. Because beta and 1.0 diverge so much, most "is this a bug or my config?" questions are answered by diffing your config and blueprint against a clean composer create-project-style install of the package.