Core Laravel Package

Getting Started

Rapidez is a Laravel package that turns a Magento 2 GraphQL backend into a headless storefront. rapidez/core is the backend half: the GraphQL client, URL/route resolution, model layer, caching, Blade/Vue scaffolding and config. The frontend theme (rapidez/checkout-theme, rapidez/account, etc.) is layered on top.

Minimum steps:

1. Composer install into a fresh Laravel app alongside the frontend package you intend to use:

   composer require rapidez/core
   

2. Point it at Magento. The storefront is useless without a Magento 2 instance exposing GraphQL. Set in .env:

   MAGENTO_BASE_URL=https://magento.test/
   MAGENTO_STORE=nl
   

   Confirm GraphQL actually answers before debugging Rapidez: curl -X POST $MAGENTO_BASE_URL/graphql -H 'Content-Type: application/json' -d '{"query":"{storeConfig{store_name}}"}'.
3. Publish config and views, then run the installer if the package ships one:

   php artisan vendor:publish --tag=rapidez-config
   php artisan vendor:publish --tag=rapidez-views
   php artisan rapidez:install   # if available in your version
   

4. Look here first, in this order:
   • config/rapidez.php — routes, cache, image config, model map, attribute lists. Almost every "why does it behave like that" question ends here.
   • routes/frontend.php (package routes) — you will see the catch-all slug route early; understand it before adding routes.
   • src/Rapidez.php and the facade — the public API you'll call daily.
   • resources/views/ — the Blade components (<x-rapidez::…>) and layout.
   • resources/js/ — Vue components registered globally; the place to extend behaviour.
5. First use case to validate the install: render a product page. Hit /{url_key} for a known product and confirm: URL rewrite resolves, GraphQL product query returns data, images render, add-to-cart hits the Magento GraphQL addSimpleProductsToCart mutation. If that loop works, the majority of your config is correct.

Expect the core package to be pinned tightly to a specific theme/frontend version. Treat a Rapidez upgrade as an upgrade of core + theme + any rapidez/* addons together, not core alone.

Implementation Patterns

GraphQL is your data layer — call it through the facade, not raw HTTP. The package wraps the Magento endpoint, injects store/locale headers, and caches responses:

use Rapidez\Core\Facades\Rapidez;

$result = Rapidez::graphql(<<<'GRAPHQL'
query Product($sku: String!) {
  products(filter: { sku: { eq: $sku } }) {
    items { name sku price_range { minimum_price { final_price { value } } } }
  }
}
GRAPHQL, ['sku' => $sku]);

$product = $result['products']['items'][0] ?? null;

Use this instead of Http::post(...) everywhere — you get the store header, error handling, and cache integration for free. Build a small repository/service class per feature (product, category, CMS block) that wraps these queries and returns plain arrays; this keeps Blade and Vue components dumb.

Model resolution via config, not hardcoding. Rapidez resolves "models" (product, category, customer, cart) through a class map in config/rapidez.php. Day-to-day you either:

• use the built-in accessors for reads: Rapidez::getModel('product') / Rapidez::model('product') (name varies by version — check src/Rapidez.php), and
• subclass the model and swap the entry in config when you need custom attributes or computed fields. This is the supported extension point; avoid editing vendor files.

Route model binding and the catch-all slug route. The frontend relies on Magento URL rewrites: a single catch-all route receives /{slug} and resolves the rewrite to a product, category or CMS page. Practical consequences:

• Define your own routes before the catch-all (order matters). Custom controller routes registered after it will never be reached.
• If a new URL type appears (landing pages, custom entities), extend the URL-rewrite resolver rather than adding a second catch-all.
• Multi-store: verify the store code is passed on every request and that URL rewrites are resolved per store view.

Views: Blade components + Vue islands. The pattern is server-rendered Blade that mounts Vue components for interactivity (cart, search, add-to-cart). Follow it:

<x-rapidez::product.price :product="$product" />
<add-to-cart :product="@js($product)" />

Override published views in resources/views/vendor/rapidez/.... Prefer publishing and overriding over view()->addNamespace() hacks, and never edit vendor/rapidez/core/resources — you'll lose it on composer update.

Caching is a first-class concern. GraphQL reads go through Laravel's cache. The workflow that works:

• Cache at the query level with a deterministic key derived from query + variables + store.
• Invalidate by tag or by bumping a version prefix after Magento content changes. Keep a small artisan command or scheduled job that clears Rapidez cache keys on catalogue/price imports, because Magento can't nuke Laravel's cache for you.
• Beware the "I changed my GraphQL query and nothing happened" trap: the key must include a version or hash of the query, otherwise stale payloads keep serving.

Integration tips that pay off:

• Attributes: extend the product/category attribute list in config so it's requested in the product GraphQL query once, then available to both Blade and Vue. Don't re-query per component.
• Images: use the package's image component/helper so Magento's media base URL and resizing parameters are applied consistently; hand-built src attributes are the usual source of broken thumbnails on staging.
• Testing: fake the Magento endpoint with Http::fake(['*/graphql' => Http::response([...])]). Because everything funnels through the facade, you can feature-test the storefront without Magento running.
• Local dev: run Magento and Laravel on separate hosts; use npm run dev for the frontend with the Laravel server pointed at the remote GraphQL. A Vite/Mix asset build is required for anything beyond localhost — a "blank page / no styles" issue is nearly always a missing build or a stale manifest.

Gotchas and Tips

• GraphQL errors are quiet. Magento returns HTTP 200 with an errors array; a naive $result['products']['items'] then throws on null. Log the errors key in your repository layer and return a sane default, otherwise you debug a 500 in Blade instead of the actual Magento message.
• The catch-all route eats your routes. Symptom: a route you added "doesn't exist" and you get a product page instead. Register before the fallback and clear the route cache (php artisan route:clear).
• Config changes need php artisan config:cache cleared. In production, editing config/rapidez.php without re-caching gives you stale store codes, stale cache TTLs and stale model bindings.
• Cache keys must include the store and locale. Multi-store setups where the Dutch site shows English prices are almost always a cache key missing the store code.
• composer update rapidez/core alone will break the frontend. Core, theme and addons share Blade component names and Vue props. Pin them to compatible minor versions and read the changelog for renamed x-rapidez:: components before upgrading.
• Don't debug in vendor/. Publish the view or config, override, and re-run php artisan view:clear. Vendor edits vanish silently on the next deploy and produce "works on my machine" ghosts.
• Vue props from Blade: @js($data) is the safe way to pass arrays; hand-written {{ json_encode(...) }} inside an attribute breaks on quotes. Hydration mismatches usually trace back to Blade rendering different data than the API returns — keep the server payload as the single source of truth.
• Media and image URLs depend on Magento's base_media_url from storeConfig. If images work in Magento but 404 in Rapidez, compare that value against MAGENTO_BASE_URL (trailing slash and subdirectory installs are common culprits).
• Debugging aid: log the exact GraphQL query and variables (and the cache key) at debug level for one request. Nine times out of ten the bug is a variable type mismatch (Int vs String for SKU/ID) or a cache key collision, not Laravel.
• Licence check: GPL-3.0. Fine for internal and self-hosted storefronts; if you plan to distribute a derived storefront commercially, review the obligations before shipping, since it's a stronger copyleft than Laravel's MIT.
• Small maintenance signal: 17 stars with a recent release date suggests a small but actively shipped package — budget time for reading source when docs are thin, and keep a local checkout of the repo for git log -p on the file you're fighting.