Statamic Butik Laravel Package

Getting Started

Statamic Butik is an e‑commerce addon for Statamic (and therefore Laravel). v4.0.0‑beta.1 is the first release targeting Statamic 4 and Laravel 9/10, so treat it as a fresh upgrade path rather than a drop‑in.

Minimal steps:

1. Confirm your stack matches: Statamic 4, Laravel 9 or 10, PHP 8.1+.
2. Install and publish:

   composer require jonassiewertsen/statamic-butik:^4.0@beta
   php artisan vendor:publish --tag="butik-config"
   php artisan vendor:publish --tag="butik-assets"
   php artisan migrate
   

3. Open config/butik.php first — it drives currency, tax, shipping methods, payment gateways, and route prefixes. Almost every early question is answered there.
4. Create a product collection (usually a products collection) with the fields Butik expects; products are just Statamic entries.
5. First use case to prove out: render a product listing with the Butik Antlers tags, add a single item to the cart, and complete a checkout against a test payment gateway. That exercises products → cart → order persistence end to end.

Where to look first: the published config, the package's routes/ and src/ directories, and the README for the current tag list. If something fails before rendering, it's almost always config or migrations, not code.

Implementation Patterns

Products as content, commerce as Eloquent. Products live as Statamic collection entries (with variants/stock as fields), while carts, orders, and customers live in database tables via Eloquent models (Order, OrderItem, Customer). Expect to work in both worlds in the same feature.

The cart is session‑backed. Cart state lives in the session and is manipulated through the Butik cart API / Antlers tags. Anything that touches the cart (adding items, quantity updates, coupon application) should go through that layer rather than writing to the session directly, so totals and tax recalculate correctly.

Checkout as a configured pipeline. A typical flow is: cart → checkout form (customer + shipping + payment selection) → gateway redirect/handling → receipt. Gateways and shipping methods are chosen by config, and the checkout controller drives the sequence. Customise by extending the gateway/shipping contracts rather than editing vendor code.

Extend via contracts and config, not overrides. Payment gateways and shipping methods are swappable through published config and their respective interfaces. Build a small custom gateway class, register it in config, and validate it with the test mode before wiring real keys.

Events for post‑order side effects. Order placement fires events suitable for listeners: sending confirmations, decrementing stock, notifying Slack/ops, syncing to an ERP. Prefer listeners over editing checkout controllers — it survives upgrades and is easier to test.

Route and middleware integration. Butik publishes its own routes (cart, checkout, receipt). If you need auth, localization, or custom middleware, apply it around these routes via config or a route group rather than patching the package.

Antlers/Blade split. Storefront rendering is Antlers (Statamic tags); admin/order management is standard Laravel/Blade. Keep presentation in templates and business rules in event listeners and service classes.

Gotchas and Tips

• This is a beta. Pin the exact version (4.0.0-beta.1) and expect breaking changes before stable. Don't ship it to production without a clear upgrade budget, and read the changelog on every bump.
• Upgrading from v3 is not a no‑op. The jump bundles a Statamic major (3 → 4) and a Laravel major. Upgrade Statamic and Laravel first, get the site stable, then install the Butik beta. Mixing both upgrades in one branch makes debugging miserable.
• Migrations and assets are easy to forget. A missing vendor:publish for assets or an unrun migrate produces confusing 500s on checkout. Add both to your deploy checklist.
• Config cache bites in production. After changing gateways, shipping, or currency in config/butik.php, run php artisan config:clear (and config:cache if you cache). Stale config is the usual cause of "my new gateway isn't showing."
• Session driver matters for the cart. File/array sessions behave differently under load and across nodes. For anything beyond local dev, use a shared store (Redis/database) so carts don't vanish between requests.
• Payment webhooks need real URLs. Local tunnel tools (ngrok/Expose) are required to test async gateway callbacks. Verify idempotency in your order listeners — webhooks can and will fire more than once.
• Money and tax are config‑sensitive. Currency formatting, tax‑inclusive vs exclusive pricing, and rounding all flow from config. Lock these down early; changing them after orders exist creates reconciliation work.
• Debugging order failures: start at the order record (was it persisted?), then the event/listener log, then gateway response. If no order exists, the failure is in checkout validation or the gateway call, not the listener.
• Extension points to prefer: gateway/shipping contracts, order events, published config, and Antlers tags. Avoid subclassing internal controllers or editing published views in place — copy views into your theme if you must override them, and keep a diff log for upgrade time.