Statamic Laravel Package

Getting Started

This is a small, low-traffic package (single-digit stars, no dependents), so treat the README as a starting point and the src/ directory as the actual documentation. Budget an hour to read the service provider and route registration before writing any code — the whole value of the package is in how it wires Statamic's routing into Rapidez's, and that's about 200 lines you can read end to end.

Install

composer require rapidez/statamic
php artisan vendor:publish --tag=statamic-config   # plus the package's own config/views
php artisan statamic:install                        # users, assets, collections, sites

Then in the Rapidez app:

1. Check config/statamic/sites.php — set url to the storefront domain(s), one site per Rapidez store view.
2. Check route registration order in routes/web.php and the package provider. Statamic registers a catch-all; every Rapidez route (product, category, cart, checkout, search, account) must be registered before it.
3. Create a pages collection with a blocks (Bard) fieldset containing one hero set.
4. Create an entry at /test-page, load it in the browser, and confirm it renders inside the Rapidez layout (Vue root mounted, header/footer present) rather than Statamic's default layout.antlers.html.

Where to look first

First real use case: a marketing landing page. It's the lowest-risk entry point — no product data, no cart interaction — and it validates the three things that will bite you later: route precedence, layout override, and how entry data reaches Vue.

Implementation Patterns

1. Let Statamic own the long tail of URLs, Rapidez own commerce. The clean mental model: Magento/Rapidez resolves anything with a catalog or session dependency; Statamic resolves everything else. Keep the fallback route last and add explicit exclusions (or a Route::has() guard) for /cart, /checkout, /account, /search so an editor creating a page slugged cart can't shadow the real route.

2. Serialize entries to JSON, render structure in Vue. Don't ship Antlers-rendered HTML and JSON for the same block. The pattern that scales:

// Controller / view composer
$payload = [
    'title'  => $entry->title,
    'blocks' => $entry->get('blocks')->map(fn ($set) => [
        'type' => $set['type'],
        'data' => $set->data()->all(),
    ]),
];

<div id="app" data-page="{{ json_encode($payload) }}"></div>

Consume in Vue with a component registry keyed on type. Always ship a fallback component for unknown types — editors will add Bard sets before the frontend is deployed, and a silent blank section is much worse than an ugly one.

3. One owner per navigation region. The most common integration smell is two sources of truth for the header. Pick: Magento category tree owns catalog navigation, Statamic globals own footer/utility/marketing links. Resolve URLs in PHP (so route()/url() semantics stay consistent) and hand Vue a flat, ready-to-render array.

4. Enrich commerce routes with CMS blocks. Rather than making whole category pages CMS-driven, extend the existing Rapidez category controller: look up an entry in a category_pages collection keyed by category_id or slug, and append its blocks below the product grid. This keeps merchandising (products, filters) in Magento and storytelling (banners, buying guides) in Statamic — the split that survives contact with a real merchandising team.

5. Globals are a per-request singleton — cache them. Nav, footer, and site settings change rarely and are needed on every page. Resolve once in a middleware or view composer, cache with a long TTL, and flush on Entry::saved. Doing this lazily inside Vue via an API call is the usual mistake: it adds a request waterfall before first paint.

6. Localization: map sites to store views explicitly. Statamic multisite and Rapidez store views are two independent concepts. Write the mapping in config (site handle → store code) rather than inferring from locale or URL prefix — inference breaks the moment you add a second language on a single store view.

7. Two content shapes, two rendering strategies.

• Structured sets (hero, USP grid, product carousel) → JSON + Vue components. Interactive, reusable, i18n-friendly.
• Prose sets (rich text, Bard text blocks, tables) → render Antlers server-side and inject as HTML. Do not attempt to reimplement a Markdown/prose renderer in Vue.

8. Custom fieldtypes for the commerce side. A product-picker or category-picker fieldtype that queries Magento (or a cached product index) is the highest-leverage extension point on this package. It turns "paste a SKU and hope" into a validated editorial workflow, and it's where you'll get the most gratitude from content editors.

Gotchas and Tips

Route order is the #1 source of "why is my page blank / 404 / showing the wrong thing." Statamic's fallback is greedy. Debug with:

php artisan route:list --path=cart
php artisan route:list | grep -i statamic

If /cart resolves to Statamic, the fallback is registered too early — check provider boot() ordering and Route::fallback() placement.

Static caching will break personalization. Statamic's static/response cache serves identical HTML to everyone. Any page carrying a cart count, customer name, or session-derived state must be excluded. If you turn on full static caching, verify with two browser sessions that the header cart is correct.

Cache invalidation doesn't cross the bridge. Statamic's cache knows nothing about Rapidez's cache tags (or vice versa). Wire an entry-saved listener to flush the relevant Rapidez tags, and a catalog-updated listener to flush the CMS payloads that embed product data. Without this you get "I updated the banner three hours ago" tickets.

Three templating layers — pick one per block and stay there. Antlers → Blade → Vue is a lot of context switching. Document the rule in the repo (structured = Vue, prose = Antlers, layout = Blade) or the next developer will duplicate the hero component in two of them.

augmentedValue() vs data(). $entry->augmentedValue('blocks') runs the Antlers renderer and gives you HTML; $entry->get('blocks') gives structured arrays with type/data. Shipping the augmented value into JSON usually means double-escaped markup. Ship structured; augment only for prose.

N+1 on Bard sets. Sets that reference entries or assets (entries fieldtype inside a block) will lazy-load. Eager-load them in the controller or cache the serialized payload — a page with 12 blocks referencing 40 entries is 40+ queries per request on a cache miss.

Asset URLs and Glide presets. Statamic image URLs may point at Glide presets that don't exist in your Rapidez CDN/image pipeline. Either configure Glide behind the same CDN or generate your own URLs from the asset path. Don't let templates emit glide:... URLs that 404 in production but work locally.

Vite vs Statamic assets are separate pipelines. Rapidez's Vite build doesn't know about resources/views/vendor/statamic. If you override a Statamic view in the app, it won't have the Vite manifest tags — copy from the package's published shell rather than starting from Statamic's stock layout.

Watch the content directory in git. content/ is flat-file YAML by default. Decide early: commit it (good for small teams, bad for non-technical editors) or move collections to a database repository and back it up. Migrating later is painful because field handles become schema.

Testing. Feature-test the payload, not the HTML: assert the JSON on #app contains the expected block types. Seed content via Statamic's testing helpers or direct entry creation; there is no factory ecosystem here. For the route bridge specifically, write one test per "must not be swallowed" route (cart, checkout, account) — that's the regression you'll actually hit.

Small-package reality check. With four stars and zero dependents, expect the READMEs to lag the code and breaking changes between minor versions. Pin the version in composer.json, read the diff before upgrading, and keep any custom glue (route guards, cache listeners) in your own app code rather than patching the vendor — you will be maintaining it.