---
url: /5.x/intro.md
---
# Intro

***

A blazing fast headless frontend for your Magento 2 webshop! Easy customisations from Laravel Blade templates with renderless Vue components. Catalog data comes from the Magento database through Laravel Eloquent for speed, everything else is using GraphQL. For filters and searching we're using InstantSearch and indexation is handled with Laravel Scout.

---

---
url: /5.x/installation.md
description: >-
  The Rapidez requirements and install instructions including info on CORS in
  Magento/Elasticsearch/OpenSearch, Multistore Nginx configuration, Magento 2
  demo shop in Docker and the Rapidez checkout standalone.
---

# Installation

***

\[\[toc]]

## Requirements

* [Laravel requirements](https://laravel.com/docs/12.x/deployment#server-requirements)
* PHP >= 8.2
* MySQL >= 8.0.28
* Elasticsearch Basic >= 8.11, or OpenSearch ^2
* Magento >= 2.4.8 ([or use a demo shop](#demo-magento-2-webshop))

::: tip Elasticsearch Basic
There are multiple Elasticsearch versions and licenses, see the [subscriptions page](https://www.elastic.co/subscriptions). Rapidez requires at least the basic version which is free but not always installed by default. Make sure you use the "full" or "non-OSS" version otherwise you'll get "no handler for type flattened" errors while [indexing](indexer.md).
:::

## Install Rapidez

1. **Start a fresh project**

```
composer create-project rapidez/rapidez:^5.0 yourproject
```

2. **Add the Magento 2 and search credentials**

When you have a Magento 2 installation running, add the URL and database credentials to the `.env`. You may also need to set your ElasticSearch/OpenSearch URL and credentials. Have a look at the [configuration docs](configuration.md) for all options. If you don't have a Magento installation running yet, we'll set one up for you with Docker from the install command. This will also set up an ElasticSearch container for you.

3. **Run the install command**

```
php artisan rapidez:install
```

4. **Explore**

Visit Rapidez within your browser! 🚀 Plenty of options there:

* [Laravel Herd](https://herd.laravel.com/)
* [Laravel Valet](https://laravel.com/docs/12.x/valet)
* `php artisan serve`

***

::: details Use in an existing Laravel project
The `rapidez/rapidez` repository contains a fresh Laravel installation with the Rapidez Core and some other packages installed to give you a good start. If you have an existing project or want to start from scratch, you can install the Rapidez packages yourself. Just have a look at the `composer.json`
:::

::: tip Magento module
Rapidez has a Companion Magento module available called [Rapidez\_Compadre](https://github.com/rapidez/magento2-compadre)
This is in no way required but adds additional functionality that we found lacking in Magento.
Current functionality can be found [here](https://github.com/rapidez/magento2-compadre#current-functionality)
:::

::: warning Product image speed
The first time product images will load slowly as they are resized on the fly. Have a look at the [Image Resizer](https://github.com/rapidez/image-resizer) package to read how this is working.
:::

## CORS

### Magento

Rapidez is making AJAX requests to the Magento API which requires CORS to be opened.

* You have to restrict this to your domain within your webserver configuration or with, for example, this [Magento 2 CORS module](https://github.com/graycoreio/magento2-cors).

When using the above module the following will probably not be necessary.

* Using Laravel Valet you can use [this](https://gist.github.com/poul-kg/b669a76fc27afcc31012aa0b0e34f738) and for Valet+, see [this](https://github.com/weprovide/valet-plus/issues/493).
* With the Docker Magento installation, it's already opened [with a patch](https://github.com/michielgerritsen/magento2-extension-integration-test/blob/master/magento/patches/cors.patch).

### Elasticsearch

If you're using your own Elasticsearch installation, you have to open CORS in `elasticsearch.yml` and restart Elasticsearch. An example can be found in the project: [`elasticsearch.yml`](https://github.com/rapidez/rapidez/blob/master/elasticsearch.yml). That configuration is used when you're using Elasticsearch from the [Docker Compose config](https://github.com/rapidez/rapidez/blob/master/docker-compose.yml).

### OpenSearch

If you're using your own OpenSearch installation you will have to open CORS in `opensearch.yml` see: [Secure OpenSearch](deployment.md#secure-opensearch).

## Multistore

When you have set up multiple stores in Magento, Rapidez needs to know which store to show. Rapidez listens to the `MAGE_RUN_CODE` like Magento does. You will have to set that variable from your webserver.

With Nginx, you could use a map, for example:

```nginx
map $http_host $MAGE_RUN_CODE {
    default default_store_code;
    second-store.com second_store_code;
    third-store.com third_store_code;
}
```

And pass that to PHP-FPM:

```nginx
fastcgi_param MAGE_RUN_CODE $MAGE_RUN_CODE;
```

## Demo Magento 2 webshop

If you do not have a Magento 2 installation yet, you want to test Rapidez, or like to develop with a fresh Magento 2 installation, you can use a Magento 2 and Elasticsearch installation in a Docker container.

::: tip
Make sure Docker can use at least 4GB of memory!
:::

If you have no webserver running on your laptop (or simply want to use a self-contained version of the project) consider using `.env.example.traefik` as your `.env`.
This will use [Traefik](https://traefik.io/traefik) to make <http://rapidez.localhost> available without any configuration necessary.

Otherwise opt for `.env.example.docker` for your `.env`.
This will give you the reins, exposing the websites on the ports defined in the `.env.example.docker`
(by default, magento: <http://127.0.0.1:1234>, rapidez: <http://127.0.0.1:1235>, elasticsearch: <http://127.0.0.1:9200>)

```bash
docker-compose up -d
docker exec rapidez_magento magerun2 indexer:reindex
```

Edit the `.env`

```dotenv
MAGENTO_URL=http://localhost:1234
DB_PORT=3307
DB_DATABASE=magento
DB_USERNAME=magento
DB_PASSWORD=password
```

## Standalone Checkout

Are you not ready to fully commit to Rapidez just yet? We support running it as a standalone checkout as well. More information can be found in the [Standalone Checkout Blog](https://rapidez.io/blog/standalone-checkout).

You will need to install [rapidez/magento2-standalone-checkout](https://github.com/rapidez/magento2-standalone-checkout) within Magento:

```bash
composer install rapidez/magento2-standalone-checkout
bin/magento module:enable Rapidez_StandaloneCheckout
```

Then you can activate it by setting your Rapidez base url under: Stores > Configuration > Rapidez > Standalone Checkout > Rapidez Url

### Credential storage

Rapidez temporarily needs to store the customers' cart mask and customer token, we save this in cache. This is usually not a problem, however if the cache gets cleared often this can lead to annoyances if the customer needs to press the checkout button multiple times. You can select a different cache store to work around this with the following ENV variable: `STANDALONE_CHECKOUT_CACHE_STORE`. We suggest copying the [Redis store in config/cache.php](https://github.com/laravel/framework/blob/79b44b168da164191950aab79ba1689f0087ccda/config/cache.php#L74) to something like `redis-persistent` and setting the connection to `default` instead of `cache`.

### Nginx

Since you're using standalone checkout you might not want to expose the other urls.
To do so you can use this nginx rule:

```nginx
# Redirect non-standalone-checkout urls to Magento.
location ~* ^\/(?!(api|healthcheck|checkout.*|mollie.+|paynl.*|msp-return)(\/|$)) {
    return 308 $scheme://<magento url>$request_uri;
}
```

---

---
url: /5.x/configuration.md
description: >-
  How to configure Rapidez, where the configuration can be found and how the
  configuration works with the Magento config.
---

# Configuration

***

You can publish all of the Rapidez config files with:

```
php artisan vendor:publish --provider="Rapidez\Core\RapidezServiceProvider" --tag="config"
```

::: tip Note
It's usually a good idea to only copy over the config files that you need to change. This can help with future updates that may end up changing things in these config files.
:::

After that, you'll find all configuration options in `config/rapidez/*.php` with comments explaining the options. Most of them use the `env()` function, so it's possible to have different configurations per environment in the `.env`.

::: tip
For more info on how the configuration works, read the [Laravel configuration docs](https://laravel.com/docs/12.x/configuration).
:::

***

\[\[toc]]

## Multistore

When you need a different configuration for a specific store, you can create a store specific configuration file: `/config/rapidez/stores/{store_code}/{config_file}` with only the changes you need compared with the default. For example, when store code `de` needs different checkout steps; create `/config/rapidez/stores/de/frontend.php` with:

```php
<?php

return [
    'checkout_steps' => [
        'onestep'
    ],
];
```

## Magento configuration

Some Magento configuration options involve the frontend. As the Magento frontend is not used, most of them don't do anything. Rapidez listens to some of those configurations, they are listed here: [`config/rapidez/magento-defaults.php`](https://github.com/rapidez/core/blob/master/config/rapidez/magento-defaults.php) with their defaults as not all of those can be queried from Magento.

If you need to access a Magento configuration, you can use the [`@config` Blade Directive](theming.html#config) or the Rapidez facade `Rapidez::config()`, which accepts the same parameters as the directive. For more advanced usage (like defining which scope), you can use:

```php
\Rapidez\Core\Models\Config::getValue($path, ConfigScopes::SCOPE_STORE, $scopeId, $options)
```

## Base URL

Rapidez will become the frontend, Magento will only be used for the backend. Because of this, they'll need two different URLs. We suggest setting the `web/secure/base_url` differently per scope. The store scope should point to your Rapidez url, and the website scope should point to your Magento url:

* **Store View:** `https://webshop.com`
* **Website:** `https://magento.webshop.com`

If you have set this correctly, you can set `GET_MAGENTO_URL_FROM_DATABASE=true` in the Rapidez `.env`, and it will automatically apply the URLs in Rapidez itself.

## Forgot password email

You have to change the URL in the forgot password email to the Rapidez URL:

```diff
- {{var this.getUrl($store,'customer/account/createPassword/',[_query:[token:$customer.rp_token],_nosid:1])}}
+ https://your-rapidez-url.com/resetpassword?token={{var customer.rp_token}}
```

### Alternatively

If you [set the store view "Base URL" to that of your Rapidez installation](configuration.html#base-url), you can keep the `getUrl()` to dynamically determine the URL.

```diff
- {{var this.getUrl($store,'customer/account/createPassword/',[_query:[token:$customer.rp_token],_nosid:1])}}
+ {{var this.getUrl($store,'resetpassword',[_query:[token:$customer.rp_token],_nosid:1])}}
```

## Customer Token Lifetime

By default, the customer token lifetime is set to 1 hour in Magento, so a customer needs to log in again when the token expires in Rapidez. It's recommended to raise the expiration to, for example, 24 hours. Check these settings in the store configuration:

* Services > OAuth > Access Token Expiration
* Services > Magento Web API > JWT Authentication > Customer JWT Expires In

## Customer Data Lifetime

When using the Standalone Checkout the default Customer Data Lifetime of 1 hour may result in the customer and/or their cart being removed in Magento. It's recommended to raise the lifetime to, for example, 3 hours. Check this setting in the store configuration:

* Customers > Customer configuration > Online Customers Options > Customer Data Lifetime

## Enable Guest Checkout Login

You can find this setting in the store configuration:

* Sales > Checkout > Checkout Options > Enable Guest Checkout Login

But keep in mind as also mentioned there:

> Enabling this setting will allow unauthenticated users to query if an e-mail address is already associated with a customer account. This can be used to enhance the checkout workflow for guests that do not realize they already have an account but comes at the cost of exposing information to unauthenticated users.

## Robots.txt

Rapidez handles the `robots.txt` route through Laravel, and can be edited by overwriting the `resources/views/robots.blade.php` view. Because this is a Laravel Blade file, you can use blade logic to do anything you want.

You can also manage part of the content through Magento. Rapidez includes the Magento robots.txt instructions by default.

::: warning 404 response
Depending on your webserver configuration, this route could end up returning a 404 response. For example, [Laravel Forge](https://forge.laravel.com/) and [Laravel Valet](https://laravel.com/docs/12.x/valet) do include a line causing this as the file could not be found:

```
location = /robots.txt  { access_log off; log_not_found off; }
```

The trick is to remove this line or extend it, depending on if you want the other log configurations:

```
location = /robots.txt  { access_log off; log_not_found off; try_files $uri $uri/ /index.php?$query_string; }
```

:::

::: tip
Make sure you double check what's in Magento's robots.txt instructions on your site. There may be a bunch of `disallow` routes that are no longer necessary!
:::

## Elasticsearch

To communicate with Elasticsearch, Rapidez is using the [rapidez/laravel-scout-elasticsearch](https://github.com/rapidez/laravel-scout-elasticsearch) package. If you need to change the Elasticsearch credentials, you can do so with these `.env` configurations:

```dotenv
ELASTICSEARCH_HOST=http://localhost:9200
ELASTICSEARCH_USER=
ELASTICSEARCH_PASSWORD=
ELASTICSEARCH_SSL_VERIFICATION=true
```

You will also need to set a prefix for your indices:

```dotenv
SCOUT_PREFIX=
```

## OpenSearch

For OpenSearch the same applies as [Elasticsearch](#elasticsearch) but you need to add this in your `.env`:

```dotenv
SCOUT_SEARCH_BACKEND=opensearch
```

## Early hints

Rapidez comes with [Early Hints](https://github.com/justbetter/laravel-http3earlyhints) built in. You should enable your early hints in [Cloudflare](https://developers.cloudflare.com/cache/advanced-configuration/early-hints/#enable-early-hints) or your CDN for a boost. Anything loaded with `@vite()` will properly get loaded with early hints, it will also discover other elements on your page which could benefit from early hints. Like your `preload` and `preconnect` links, eager-loaded images, blocking scripts, and blocking styles. You can disable it with:

```dotenv
EARLY_HINTS_ENABLED=false
```

::: tip
You should [preload your custom fonts](https://web.dev/articles/codelab-preload-web-fonts) if they're used during the initial render.
:::

---

---
url: /5.x/upgrading.md
description: >-
  Upgrade info from Rapidez v4 to Rapidez v5 including all changes like the
  removal of the Magento flat tables dependency, the Vue 3 and Tailwind 4
  upgrade, new features like customer group pricing, tier pricing, product media
  videos and cache tags with step-by-step info on how to upgrade. There is also
  a prompt to automate the upgrade.
---

# Upgrading

***

\[\[toc]]

## Rapidez v5

In this release, we removed the [flat tables dependency](https://github.com/rapidez/core/pull/943)! 🚀 And we also updated to [Vue 3](https://github.com/rapidez/core/pull/951) and [Tailwind 4](https://github.com/rapidez/core/pull/1211) 🤘🏻 We also added support for:

* [Customer group pricing](https://github.com/rapidez/core/pull/1074)
* [Tier pricing](https://github.com/rapidez/core/pull/1205)
* [Product media videos](https://github.com/rapidez/core/pull/1128)
* [Cache tags](https://github.com/rapidez/core/pull/1103)

Other changes included in this release:

* [Drop support for Laravel 11](https://github.com/rapidez/core/pull/1096)

Some of these are quite substantially breaking changes. On this page we'll mention the most important things that you will need to do to upgrade.

You should review [all template/config changes](https://github.com/rapidez/core/compare/4.x..master) and check the [full changelog](https://github.com/rapidez/core/releases).

:::tip
For any major update, you should be aware that all overwritten Blade, Vue, and PHP files will need to be checked. Checking the above diff is the quickest way to tell where you need to make changes.
:::

## Composer dependencies

Check all your dependencies one by one to see if they're compatible and what has changed in changelogs / release notes. To get a nice overview, run the following command:

```bash
composer outdated
```

## Vue 3

### Dependencies

1. **Remove**

```bash
yarn remove @vitejs/plugin-vue2 vue-clickaway vue2-teleport vue-template-compiler
```

2. **Install**

```bash
yarn add -D @vitejs/plugin-vue vue3-click-away
```

And update your `vite.config.js`

```diff
  import path from 'path'
  import { defineConfig } from 'vite'
  import laravel from 'laravel-vite-plugin'
- import vue from '@vitejs/plugin-vue2'
+ import vue from '@vitejs/plugin-vue'
  import { visualizer } from 'rollup-plugin-visualizer'

  export default defineConfig({
...
          alias: {
              '@': path.resolve(__dirname, './resources/js'),
              Vendor: path.resolve(__dirname, './vendor'),
-             vue: path.resolve(__dirname, './node_modules/vue/dist/vue.esm.js'),
+             vue: 'vue/dist/vue.esm-bundler.js',
          },
      },
  })
```

3. **Upgrade the other dependencies**

```bash
yarn add -D @vueuse/core @vueuse/integrations cross-env instantsearch.js laravel-vite-plugin vite vue
```

4. **Upgrade your scripts and templates**

This will require some work but we've got a list of things to check. Please read the [Vue 3 migration guide](https://v3-migration.vuejs.org/). Some recurring themes we've run into:

* [Dropped support for global $emit and $on](https://v3-migration.vuejs.org/breaking-changes/events-api#event-bus), For this we've [built a system on regular events](https://github.com/rapidez/core/blob/cecc136e5ef76dc4925186a332f875d3ffe658fe/resources/js/polyfills/emit.js#L18). You should replace `$root.$on`/`window.app.$on` with `window.$on`.
* Check for any `v-if`s in combination with `v-for`, see: [If used on the same element, v-if will have higher precedence than v-for](https://v3-migration.vuejs.org/breaking-changes/v-if-v-for.html)
* Rename all `slot-scope` to `v-slot` and move them to the component in your template
* The `price`, `truncate` and `url` filters no longer work, replace `@{{ final_price | price }}` with `@{{ price(final_price) }}` as well as `$options.filters.price(final_price)` with `price(final_price)`
* Any custom async components must be wrapped by `defineAsyncComponent`: `() => import('...')` to `defineAsyncComponent(() => import('...'))`
* `window.app` no longer contains the custom variables. Replace `window.app.<...>` e.g. `cart`  with `window.app.config.globalProperties.<...>` or if you’re within vue templates directly do `<...>`
* When inside js functions all computed (refs) must be retrieved with `.value`. Examples are: `cart.value`, `user.value`, `token.value`, `mask.value`, `loading.value`
* All calls to `Vue.set` calls should be removed, and replaced by setting the variable directly.

5. **Build**

```bash
yarn build
```

:::tip
We recommend to double check all frontend dependencies with `yarn outdated`.
:::

## Tailwind v4

1. **Migrate to Vite**

If you are using Vite, we recommend migrating from the PostCSS plugin. Add this to your `vite.config.js`:

```diff
+ import tailwindcss from "@tailwindcss/vite";
  export default defineConfig({
...
    plugins: [
+       tailwindcss(),
    ]
  })
```

Then you need to install `@tailwindcss/vite`:

```bash
yarn add -D @tailwindcss/vite
```

2. **Update to Tailwind CSS 4**

Tailwind CSS has a built-in upgrade tool that can be found in the [Tailwind CSS docs](https://tailwindcss.com/docs/upgrade-guide#using-the-upgrade-tool).

```bash
npx @tailwindcss/upgrade
```

It is still necessary to review the changes that are made when the upgrade is done. Check if all [deprecated utilities](https://tailwindcss.com/docs/upgrade-guide#removed-deprecated-utilities) are changed.

```diff
- class="bg-black bg-opacity-50 flex-shrink-0"
+ class="bg-black/50 shrink-0"
```

Also check the [renamed utilities](https://tailwindcss.com/docs/upgrade-guide#renamed-utilities)

```diff
- class="ring outline-none"
+ class="ring-3 outline-hidden"
```

3. **Custom classes**

Since Rapidez v3, we have made changes to use [default colors](https://docs.rapidez.io/3.x/theming.html#colors), so we can use classes like `bg`, `text`, or `border`. In Rapidez v5, we removed the colors from the `rapidez/core` and added them inside the [blade components](https://github.com/rapidez/blade-components/blob/master/resources/css/components/rapidez.css).

4. **Build**

```bash
yarn build
```

:::tip
We recommend to double check all changes that are made after the update.
:::

## Flat tables

This update gets rid of the dependency on the Magento flat tables. This means that they can be disabled entirely (both the product and category tables) in your magento configuration, which should speed up the indexing process in Magento substantially.

However, this also means that any and all custom queries, scopes, relationships, custom attributes, and model overwrites may need to be upgraded.

### Scopes

Any custom scopes added to product or category models that affect the SQL query directly (e.g. with a join) will need to be checked. In some cases they will need to be completely refactored (For example: see [this package update](https://github.com/rapidez/amasty-automatic-related-products/compare/4.0.0...5.0.0)).

### Relationships

Relationships that relate to `entity_id` (or also `sku` on the product model) will be unaffected.

### Attribute changes

The base product and category models now query the `catalog_product_entity` and `catalog_category_entity` tables. All of the attributes get added by using relations, which means you won't have direct access to attribute data in queries anymore. We have created a `whereAttribute` helper for this. For example:

```diff
-Product::where('color', 'red')->get();
+Product::whereAttribute('color', 'red')->get();
```

The way you retrieve attribute values from a product or category model has also changed somewhat. Where previously you would retrieve values directly from the object, you should now use one of the `->label()`, `->value()`, and `->raw()` functions. For product specifications, updating this may look something like:

```diff
-<dd>{{ $product->climate }}</dd>
+<dd>{{ $product->label('climate') }}</dd>
```

Note that the `->value()` function will be used by default, which will return the actual value as given in the database. This means that text attributes and numeric attributes will usually not need to be updated. For example, `$product->name` doesn't need to be changed. This change should only be relevant for attributes where the displayed value comes from the `eav_attribute_option_value` table.

### Overwrites

If you've overwritten any model classes that relate to products/categories or the `ProductController` class: these files have changed significantly. You should migrate these carefully by looking at the full diff of these models.

Frontend overwrites will also need to be checked individually. You should look at the diff linked at the start of this page.

## Other changes

### Variables on the product model

These specific variables have been removed and should be replaced like so:

| Variable | Replacement | Extra info |
|---|---|---|
| `->min_sale_qty` | `->stock->min_sale_qty` | |
| `->max_sale_qty` | `->stock->max_sale_qty` | |
| `->qty_increments` | `->stock->qty_increments` | |
| `->in_stock` | `->stock->is_in_stock` | |
| `->upsell_ids` | `->upsells()->pluck('linked_product_id')` | Depending on the situation, using `->upsells->pluck('linked_product_id')` may be more fitting. |
| `->relation_ids` | `->relationProducts()->pluck('linked_product_id')` | Same as above |
| `->grouped` | `->children` | These returned the same list already, this is just for simplicity. |
| `->images` | `->media` | This is no longer an array of image urls, but with an 'image' key. |
| `->reviews_count` | `->reviewSummary->reviews_count` | |
| `->reviews_score` | `->reviewSummary->reviews_score` | |

Also check these values in javascript syntax (instead of `->` checking `.`).

### Translation strings

A few translations strings have been changed and added:

| Old | New |
|---|---|
| Firstname | First name |
| Middlename | Middle name |
| Lastname | Last name |
| Housenumber | House number |

| Added |
|---|
| Show more |

Translation files, as well as usage of these translations, should be changed accordingly.

## Using AI?

::: details Using AI? This prompt will give you a head start! Do still check everything manually.
This is a large prompt, we suggest using tools like [Chief](https://chiefloop.com/) to turn it into separate tasks so AI has a smaller chance of making mistakes.

````markdown
# Rapidez v5 Upgrade Prompt

You are an expert Laravel, Magento, Vue, and Tailwind developer tasked with upgrading a Rapidez project to v5.

Use this as a strict migration checklist and implementation guide. Favor concrete code changes over high-level advice.

## Goal

Upgrade a Rapidez project to v5, including:

- Vue 2 to Vue 3 migration
- Tailwind CSS v4 migration
- Flat table removal compatibility updates
- Product model API changes
- Translation string updates

## Important Context

- Rapidez v5 removes dependency on Magento flat tables
- Rapidez v5 uses Vue 3
- Rapidez v5 uses Tailwind CSS 4
- All overwritten Blade, Vue, and PHP files must be reviewed
- Review template/config diff: https://github.com/rapidez/core/compare/4.x..master
- Review full releases/changelog (for 5.x versions): https://github.com/rapidez/core/releases

## 1. Dependency Upgrade Sequence

### 1.1 Composer dependencies

Run and evaluate all incompatible packages:

```bash
composer outdated
```

### 1.2 Frontend dependencies for Vue 3

Remove Vue 2 packages:

```bash
yarn remove @vitejs/plugin-vue2 vue-clickaway vue2-teleport vue-template-compiler
```

Install Vue 3 packages:

```bash
yarn add -D @vitejs/plugin-vue vue3-click-away
```

Upgrade related frontend dependencies:

```bash
yarn add -D @vueuse/core @vueuse/integrations cross-env instantsearch.js laravel-vite-plugin vite vue
```

## 2. Vite Configuration Changes

Update `vite.config.js` for Vue 3 and Tailwind v4.

```diff
  import path from 'path'
  import { defineConfig } from 'vite'
  import laravel from 'laravel-vite-plugin'
- import vue from '@vitejs/plugin-vue2'
+ import vue from '@vitejs/plugin-vue'
+ import tailwindcss from '@tailwindcss/vite'
  import { visualizer } from 'rollup-plugin-visualizer'

  export default defineConfig({
      plugins: [
+         tailwindcss(),
          laravel({
              input: [...],
              refresh: true,
          }),
          vue(),
      ],
      resolve: {
          alias: {
              '@': path.resolve(__dirname, './resources/js'),
              Vendor: path.resolve(__dirname, './vendor'),
-             vue: path.resolve(__dirname, './node_modules/vue/dist/vue.esm.js'),
+             vue: 'vue/dist/vue.esm-bundler.js',
          },
      },
  })
```

Install Tailwind Vite plugin:

```bash
yarn add -D @tailwindcss/vite
```

## 3. Vue 2 to Vue 3 Migration Rules

Apply these across all Blade and Vue customizations.

### 3.1 Slots: `slot-scope` to `v-slot`

```vue
<!-- Vue 2 -->
<graphql query="...">
    <div slot-scope="{ data, loading }">
        <!-- content -->
    </div>
</graphql>

<!-- Vue 3 -->
<graphql query="..." v-slot="{ data, loading }">
    <div>
        <!-- content -->
    </div>
</graphql>
```

If a `<template>` tag is used, keep `v-slot` on that template:

```vue
<!-- Vue 2 -->
<component>
    <template slot-scope="{ data }">
        <!-- content -->
    </template>
</component>

<!-- Vue 3 -->
<component>
    <template v-slot="{ data }">
        <!-- content -->
    </template>
</component>
```

### 3.2 Filters are removed

```blade
{{-- Vue 2 (invalid in Vue 3) --}}
@{{ final_price | price }}
@{{ product.url | url }}

{{-- Vue 3 --}}
@{{ price(final_price) }}
@{{ url(product.url) }}
```

Also replace `truncate` filter usage with a helper/function call.

### 3.3 Event bus migration

Global Vue instance events are removed.

```javascript
// Vue 2
this.$root.$on('event-name', handler)
window.app.$on('event-name', handler)

// Vue 3 in Rapidez
window.$on('event-name', handler)
window.$emit('event-name', payload)
```

Recommended convention for custom events:

- Prefix custom events with `rapidez:`
- Example: `rapidez:cart-updated`

### 3.4 Global properties and refs

```javascript
// Vue 2
window.app.cart
this.cart

// Vue 3
window.app.config.globalProperties.cart
this.cart.value
```

In JS functions, refs must use `.value` (for example `cart.value`, `user.value`, `token.value`, `mask.value`, `loading.value`).

### 3.5 Async components

```javascript
// Vue 2
() => import('./MyComponent.vue')

// Vue 3
import { defineAsyncComponent } from 'vue'
defineAsyncComponent(() => import('./MyComponent.vue'))
```

### 3.6 Remove `Vue.set`

```javascript
// Vue 2
Vue.set(this.object, key, value)

// Vue 3
this.object[key] = value
```

### 3.7 `v-if` and `v-for` precedence changed

`v-if` now has higher precedence than `v-for`.

```vue
<!-- risky pattern -->
<div v-for="item in items" v-if="item.active">

<!-- safer Vue 3 pattern -->
<template v-for="item in items" :key="item.id">
    <div v-if="item.active">
        ...
    </div>
</template>
```

### 3.8 Render functions and slots

```javascript
// Vue 2
render() {
    return this.$scopedSlots.default(this)
}

// Vue 3
render() {
    return this?.$slots?.default(this)
}
```

### 3.9 `v-text` and `v-html` with fallback content

If elements with `v-text` or `v-html` contain inner fallback content, replace with `v-txt` and `v-htm` patterns used by Rapidez migration tooling.

```vue
<!-- before -->
<div v-text="scopeProps.value">Default value</div>

<!-- after -->
<div v-txt="scopeProps.value">Default value</div>
```

```vue
<!-- before -->
<div v-html="scopeProps.value">Default value</div>

<!-- after -->
<div v-htm="scopeProps.value">Default value</div>
```

### 3.10 Component emits and v-model

For components that emit events, add explicit `emits` declarations and migrate `value` props to `modelValue` where applicable.

```javascript
export default {
    props: {
        modelValue: {
            default: 1,
        },
    },
    emits: ['update:modelValue', 'input', 'change'],
    computed: {
        value: {
            get() {
                return this.modelValue
            },
            set(value) {
                this.$emit('update:modelValue', value)
            },
        },
    },
}
```

# 3.11 Check blade components

On any blade component (`<x-*>`) it is no longer possible to add `v-*` attributes without value and must be replaced with empty values `v-*=""`.
For example attributes like `<x-heroicon-o-chevron-down v-else />` must be changed to `<x-heroicon-o-chevron-down v-else="" />`.

# 3.12 Check the migration docs

When in doubt view the [Vue 3 migration guide](https://v3-migration.vuejs.org/)

## 4. Tailwind CSS v4 Migration

Run official upgrade tool:

```bash
npx @tailwindcss/upgrade
```

Then manually review deprecated and renamed utility classes.

Examples:

```diff
- class="bg-black bg-opacity-50 flex-shrink-0"
+ class="bg-black/50 shrink-0"
```

```diff
- class="ring outline-none"
+ class="ring-3 outline-hidden"
```

Also verify custom color classes. Rapidez v5 moved colors out of core and into blade components CSS.

Verify all steps from https://tailwindcss.com/docs/upgrade-guide have been executed and run any other checks that need to be done.

## 5. Flat Table Removal Migration

Rapidez v5 queries `catalog_product_entity` and `catalog_category_entity` directly through attribute relations.
Compare the `./config/rapidez/*.php` with `./vendor/rapidez/*/config/rapidez/*.php` and add any missing entries in the overwritten config files.

### 5.1 Query constraints on attributes

Direct `where` on EAV attributes may no longer work in custom scopes.

```php
// before
Product::where('color', 'red')->get();

// after
Product::whereAttribute('color', 'red')->get();
```

### 5.2 Attribute value access

Use `label()`, `value()`, and `raw()` when needed.

```php
// before
$product->climate

// after (for option labels)
$product->label('climate')
```

Keep simple text/number attributes as-is if they map correctly via default `value()` behavior.

### 5.3 Scopes and relationships

- Revisit custom scopes that used joins against flat tables
- Relationships on `entity_id` (and `sku` on products) are generally unaffected
- Carefully review all product/category model overrides and any `ProductController` overrides

## 6. Product Model API Replacements

Replace removed product properties with new equivalents:

| Removed | Replacement |
|---|---|
| `->min_sale_qty` | `->stock->min_sale_qty` |
| `->max_sale_qty` | `->stock->max_sale_qty` |
| `->qty_increments` | `->stock->qty_increments` |
| `->in_stock` | `->stock->is_in_stock` |
| `->upsell_ids` | `->upsells()->pluck('linked_product_id')` |
| `->relation_ids` | `->relationProducts()->pluck('linked_product_id')` |
| `->grouped` | `->children` |
| `->images` | `->media` |
| `->reviews_count` | `->reviewSummary->reviews_count` |
| `->reviews_score` | `->reviewSummary->reviews_score` |

Note: `->media` is not the old plain URL array shape and now includes richer media data (including video support).

## 7. Translation String Updates

Update both translation files and template usage:

| Old | New |
|---|---|
| Firstname | First name |
| Middlename | Middle name |
| Lastname | Last name |
| Housenumber | House number |

Also add:

- `Show more`

## 8. Validation and Build Checklist

Run and fix issues iteratively:

```bash
yarn outdated
yarn build
```

Manual validation checklist:

1. Verify all overridden Blade/Vue/PHP files against v5 core diff
2. Test custom events migrated to `window.$on`/`window.$emit`
3. Verify all ref access in JS uses `.value`
4. Check all migrated slots render correctly
5. Verify Tailwind class updates and custom theme behavior
6. Test product/category custom queries and scopes
7. Verify media rendering (images and videos)
8. Validate pricing (including customer group and tier pricing)
9. Run checkout and cart interaction smoke tests

## 9. Execution Rules for the AI

When performing the migration:

1. Make minimal, targeted changes
2. Preserve project-specific conventions
3. Prefer mechanical, auditable diffs
4. Flag uncertainty explicitly (do not silently guess)
5. Always provide a final list of changed files and why each was changed
6. After code edits, provide a focused manual QA checklist based on touched areas

## 10. Refinement

### Blade overrides

Compare the resources/views/vendor folder with their vendor/rapidez/*/resources/views counterparts.
And place a comment at the top of the blade files we have overwritten describing what has been overwritten.
````

:::

---

---
url: /5.x/deployment.md
description: How to deploy Rapidez to a server / production?
---

# Deployment

***

\[\[toc]]

## Checklist

* Check the [Laravel deployment docs](https://laravel.com/docs/12.x/deployment)
* Make sure the server meets the [requirements](installation.md#requirements)
* Check all [configurations](configuration.md)
* [Configure CORS](installation.md#cors)
* If you're upgrading, check the [upgrade notes](upgrading.md)
* Configure the [indexer](indexer.md) in the [scheduler](indexer.md#scheduler) or with [webhooks](indexer.md#webhook)
* [Redirect Magento](#redirecting-magento)
* [Secure Elasticsearch](#secure-elasticsearch)
* Check your `.env`
  * Set `APP_ENV` to `production`
  * Change the `RAPIDEZ_TOKEN` to something random
  * Make sure these values are `false`
    * `APP_DEBUG`
    * `VITE_DEBUG`
    * `DEBUGBAR_ENABLED`
  * Make sure that your `CRYPT_KEY` is set to the same value as in your Magento installation
* Optionally [configure your multistore](installation.md#multistore)
* Optionally [setup full page caching](cache.md#full-page-caching)
* Make sure your deployment script is complete. You may need, for example (in this order):
  * `php artisan migrate --force`
  * `php artisan optimize:clear`
  * `php artisan icons:cache`
  * `php artisan optimize`
  * If you're using Statamic with static caching, `php please static:clear` at the end
* Issues? Check see [troubleshooting](troubleshooting.md)

## Redirecting Magento

The Magento frontend should not be accessible anymore as you're using Rapidez. But GraphQL, media, admin, etc should be reachable. Create a redirect rule to accomplish that, for example with Nginx:

```nginx
location ~* ^\/(?:index\.php\/)?(rest|graphql|oauth|pub|static|sales|media|admin)(\/|$)) {
    return 301 $scheme://your-rapidez-url.com$request_uri;
}
```

Some packages may require additional entries into this regex (for example, [rapidez/multisafepay](https://github.com/rapidez/multisafepay)), make sure to check the readme.

Make sure to change the admin location and URL. Place this below the Magento location directives, for example [here in the sample Nginx config](https://github.com/magento/magento2/blob/203a44f9e755fa6d2e057f1b99efbaff17546a80/nginx.conf.sample#L222).

## Secure Elasticsearch

You have to secure your Elasticsearch instance so other people can't manipulate the data in it as it needs to be exposed for InstantSearch.

* Enable security in `elasticsearch.yml` with: `xpack.security.enabled: true`
  * On Ubuntu: `/etc/elasticsearch/elasticsearch.yml`
* Change `http.cors.allow-origin` to your domain
* Restart Elasticsearch
  * On Ubuntu: `sudo service elasticsearch restart`
  * With Docker: `docker restart rapidez_elasticsearch`
* Setup a password with `bin/elasticsearch-setup-passwords auto` (or use `interactive` to choose the passwords yourself)
  * On Ubuntu, from: `cd /usr/share/elasticsearch/`
  * With Docker, prefix with: `docker exec rapidez_elasticsearch `
* Add your credentials to `.env`

```dotenv
ELASTICSEARCH_USER=elastic
ELASTICSEARCH_PASSWORD=YOUR-PASSWORD
```

* Create a proxy (with SSL) on a subdomain

```nginx
location / {
        proxy_pass http://localhost:9200;
}
```

### Kibana

::: tip No Kibana running?
You can also secure Elasticsearch without it, see: [Without Kibana](#without-kibana)
:::

* Repeat this step for Kibana which should be running on port 5601
* Set the credentials in `kibana.yml`

```yaml
elasticsearch.username: "elastic"
elasticsearch.password: "YOUR-PASSWORD"
```

* Login to Kibana and go to Management > Roles
* Add a new role `web`. It only needs one index privilege; use `rapidez_*` for the indices and `read` as privilege.
* Create a user `web`, password `rapidez` and the `web` role
* Add the URL to your `.env`

```dotenv
ELASTICSEARCH_URL=https://web:rapidez@elasticsearch.domain.com
```

### Without Kibana

Run the following commands:

```bash
# Create the role `web` that may read `rapidez_*` indexes
curl -X POST "localhost:9200/_security/role/web?pretty" -H 'Content-Type: application/json' -d'
{
  "indices": [
    {
      "names": [ "rapidez_*" ],
      "privileges": ["read"]
    }
  ]
}
' -u username:password
```

Then create the user.

```bash
# Create the user `web` with password `rapidez`
curl -X POST "localhost:9200/_security/user/web?pretty" -H 'Content-Type: application/json' -d'
{
  "password" : "rapidez",
  "roles" : [ "web" ]
}
' -u username:password
```

Finally add the URL to your `.env`

```dotenv
ELASTICSEARCH_URL=https://web:rapidez@elasticsearch.domain.com
```

## Secure OpenSearch

You have to secure your OpenSearch instance so other people can't manipulate the data in it as it needs to be exposed for InstantSearch. Add this in your [`opensearch.yml`](https://docs.opensearch.org/docs/latest/install-and-configure/configuring-opensearch/index/#configuration-file)

```yaml
http.cors.enabled: true
http.cors.allow-credentials: true
http.cors.allow-origin: "https://your-rapidez-store.com"
http.cors.allow-headers: X-Requested-With, X-Auth-Token, Content-Type, Content-Length, Authorization, Access-Control-Allow-Headers, Accept
```

You will need to create a rapidez/web user as well in the [`internal_users.yml`](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#internal_usersyml)

```yaml
web:
  hash: "WEB_PASSWORD_REPLACEME"
  reserved: true
  backend_roles:
  - "rapidez"
  description: "Public web user"
```

Then link that user to the role we are about to create in the [`roles_mapping.yml`](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#roles_mappingyml)

```yaml
rapidez:
  reserved: false
  users:
  - "web"
  backend_roles:
  - "rapidez"
  description: "Allow read only access to indexes prefixed with rapidez_"
```

Create the role with the correct permissions to the `rapidez_` indexes in the [`roles.yml`](https://docs.opensearch.org/docs/latest/security/configuration/yaml/#rolesyml)

```yaml
rapidez:
  reserved: false
  cluster_permissions:
    - "indices:data/read/msearch"
    - "indices:data/read/msearch/template"
  index_permissions:
    - index_patterns:
        - 'rapidez_*'
      allowed_actions:
        - "indices:data/read/scroll"
        - "indices:data/read/scroll/clear"
        - "indices:data/read/mget"
        - "indices:data/read/mget*"
        - "indices:data/read/search"
        - "indices:data/read/search*"
        - "indices:data/read/msearch"
        - "indices:data/read/msearch/template"
        - "indices:data/read/search/template"
        - "indices:data/read/mtv"
        - "indices:data/read/mtv*"
        - "indices:data/read/search/template/render*"
```

## Magento 2 Docker

::: warning
This is only needed if you'd like to run the [Magento 2 demo webshop](installation.md#demo-magento-2-webshop) on a server.
:::

Just proxy everything to a subdomain and use that domain as `MAGENTO_URL` in the `.env`. With Laravel Forge this is really easy; just create another website on your server, setup SSL and edit the Nginx config

```nginx
location / {
    proxy_pass http://127.0.0.1:1234;
    proxy_redirect off;
    proxy_read_timeout 60;
    proxy_connect_timeout 60;
    
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}
```

Use the MySQL credentials from the container in the `.env`

```dotenv
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3307
DB_DATABASE=magento
DB_USERNAME=magento
DB_PASSWORD=password
```

---

---
url: /5.x/faq.md
description: Some non-technical questions and answers.
---

# FAQ

***

\[\[toc]]

## Why is it so fast?

> Because Rapidez does not use the Magento frontend stack. Just Laravel on top of the Magento database through Laravel Eloquent for catalog data and GraphQL for other parts like the cart and checkout. Category filters are so fast because of InstantSearch which uses Elasticsearch/OpenSearch. For the smooth page transitions Rapidez uses Turbo.

## Why headless and not a PWA?

> Do you really need an offline experience on your webshop? PWA makes things more complicated than necessary.

## Why query the Magento database instead of using GraphQL everywhere?

> Speed! The Magento database structure hasn't changed much over the years, and Rapidez is just using it to read data. Changes will go through GraphQL.

## Are all product types supported?

> Simple, configurable, downloadable, and grouped product types are currently supported.

## Do I need to know Vue?

> No, Vue is only used for some functional frontend components like the cart. All Vue components are "renderless", so most likely you never need to touch them because all the HTML is in the Blade files. But some basic knowledge of Vue could be useful.

## Tailwind CSS is used, do I need to use it?

> No, you do not need to use it. You are completely free to use whatever you want. We like it, so we use it for basic styling.

## Is it production ready?

> Absolutely! Check out some [showcases](https://rapidez.io/showcases) to see live projects! Please [let us know](https://github.com/rapidez/rapidez/discussions) if you're missing something.

---

---
url: /5.x/troubleshooting.md
description: The first thing to check when there are issues.
---

# Troubleshooting

***

* Make sure Magento is functioning correctly.
* Validate the settings using `php artisan rapidez:validate`.
* Clear all of the application cache by running `php artisan optimize:clear`.
* Check if you're using full page caching (e.g. statamic's static caching) and clear that.
  * Tip: You can also work around cache entirely by adding a random query parameter to the end of your url.
* Reindex the products by executing `php artisan rapidez:index`.
* Clear the browser cache. In Google Chrome, click on the "Clear site data" button located on the application tab in DevTools.
* Join the [Rapidez Slack](https://rapidez.io/slack) and ask your questions!

---

---
url: /5.x/theming.md
description: >-
  Everything about Rapidez views, CSS, Tailwind CSS, color variables,
  Javascript, Blade Directives, Blade Components, Blade Icons, Vue Directives,
  Vue helpers, multistore setup and translations.
---

# Theming

***

The base theming is located within `rapidez/core` which you can publish to your project and change it. Alternatively, you can [create your own package](package-development.md) with views, CSS, and Javascript like a theme.

::: tip
Read the [Laravel Blade Templates docs](https://laravel.com/docs/12.x/blade) before you begin.
:::

\[\[toc]]

## Views

To change the views, you can publish them with:

```bash
php artisan vendor:publish --provider="Rapidez\Core\RapidezServiceProvider" --tag=views
```

After that, you'll find all the Rapidez Core views in `resources/views/vendor/rapidez`. For more information, see [Overriding Package Views](https://laravel.com/docs/12.x/packages#overriding-package-views) in the Laravel docs.

::: tip
It's recommended to only add the views you've changed into your source control for upgradability. To keep track of what you've changed in a view, it's a good idea to add the unchanged version to version control before you make any changes.
:::

### Update vendor hashes

Rapidez comes bundled with a template diff composer plugin. It will automatically add and update the following line in vendor templates you overwrite:

```blade
{{-- vendor-hash:VENDOR_FILE_MD5_HASH --}}
```

It runs on every `composer update`. If this hash changes you know the file you have overwritten has been changed upstream and should be checked.
Since it only runs on `composer update` it may not run when first publishing the views.
You can run `composer update-vendor-hashes` to manually trigger updating the vendor hashes.

## CSS

We're using [Tailwind CSS](https://tailwindcss.com) with [Vite](https://laravel.com/docs/12.x/vite), so probably you don't need to touch the CSS, but if you need to add a simple class, the "starting point" is [`resources/css/app.css`](https://github.com/rapidez/rapidez/blob/master/resources/css/app.css). This file will be overwritten with the [install command](installation.html#install-rapidez) with the [`app.css` from the core](https://github.com/rapidez/core/blob/master/resources/publishables/resources/css/app.css).

::: details But... I don't like Tailwind CSS
If you don't like Tailwind CSS you *can* use anything else. But it's widely used in Rapidez packages, so we don't recommend it. Just clear out the [`resources/css/app.css`](https://github.com/rapidez/rapidez/blob/master/resources/css/app.css) and write your own.
:::

### Colors

Colors can be configured from `resources/css/app.css` and all colors used by Rapidez can be found within the [`rapidez/blade-components` package](https://github.com/rapidez/blade-components/blob/master/resources/css/components/rapidez.css). This is just a starting point to easily change the whole look and feel with some variables. We advice you to use those variables / classes as much as possible but you're free to use anything else.

The colors variables are inspired by [GitHub Primer](https://primer.style/) where Tailwind CSS provides the "base color tokens", see: [design token categories](https://primer.style/foundations/color/overview#design-token-categories) and within the [`rapidez/blade-components` package](https://github.com/rapidez/blade-components/blob/master/resources/css/components/rapidez.css) we're just "aliasing" those to "functional color tokens". More information about the color naming can be found in the [color names refactor pull request](https://github.com/rapidez/core/pull/622).

#### Semantic colors

These colors can be used to apply your branding. There is one "modifier" by default provided: `text`. That color modifier is used for the text on top of the color, for example with buttons. The `conversion` color is used for anything "conversion" related.

Color name | CSS variable | Default color | |
:--- | :--- | :--- | :---
`primary` | `--primary` | `#2FBC85` | {.np}
`primary-text` | `--primary-text` | `white` | {.np}
`secondary` | `--secondary` | `#202F60` | {.np}
`secondary-text` | `--secondary-text` | `white` | {.np}
`conversion` | `--conversion` | `green-700` | {.np}
`conversion-text` | `--conversion-text` | `white` | {.np}

These color names work the same as Tailwind colors. You can use them for anything, for exmaple: `bg-primary`, `border-primary`, `text-primary`, etc.

#### Neutral colors

Used for the text color, borders, backgrounds, rings and outlines to give some design system to work with. Visual examples can be found with in the [Primer neutral colors docs](https://primer.style/foundations/color/overview#neutral-colors). These colors should not be used directly: ~~`text-foreground`~~ as those colors are "linked and scoped" to the text, border, background, ring and outline colors. Just use the provided classes to keep a consistent style.

##### Text / Foreground

Class | CSS variable | Default color | |
:--- | :--- | :--- | :---
`text-emphasis` | `--foreground-emphasis` | `slate-900` | {.np}
`text` / `text-default` | `--foreground` | `slate-800` | {.np}
`text-muted` | `--foreground-muted` | `slate-600` | {.np}

##### Border, ring and outline

Class | CSS variable | Default color | |
:--- | :--- | :--- | :---
`border-active` | `--border-active` | `slate-800` | {.np}
`border-emphasis` | `--border-emphasis` | `slate-400` | {.np}
`border` / `border-default` | `--border` | `slate-300` | {.np}
`border-muted` | `--border-muted` | `slate-100` | {.np}

> Ring and outline colors are the same as the border colors, you can use them like: `outline-emphasis` and `ring-emphasis`.

##### Background

Class | CSS variable | Default color | |
:--- | :--- | :--- | :---
`bg-active` | `--background-active` | `slate-800` | {.np}
`bg-emphasis` | `--background-emphasis` | `slate-200` | {.np}
`bg` / `bg-default` | `--background` | `slate-100` | {.np}
`bg-muted` | `--background-muted` | `slate-50` | {.np}

##### Backdrop

A slightly transparant background visible when a slideover or the autocomplete is open.

Class | CSS variable | Default color | |
:--- | :--- | :--- | :---
`backdrop` | `--backdrop` | `rgba(0, 0, 0, 0.4)` | {.np}

## Javascript

We automatically import everything in `resources/js/app.js`, and you can extend from there. If you need additional Vue components, read the [readme within the components folder](https://github.com/rapidez/rapidez/blob/master/resources/js/components/README.md).

## Blade Directives

Rapidez provides some Blade Directives to easily get information from Magento.

::: warning Caching
Keep in mind the output of these directives is cached! So after changing a configuration, block, or widget, the cache needs to be cleared. See the [caching docs](cache.md).
:::

### `@config`

Get a config value for the current store scope with optionally a fallback, example:

```blade
@config('general/locale/timezone', 'Europe/Amsterdam')
```

A third parameter can be set to `true` when it's a sensitive/encrypted config.

### `@block`

Get the block contents for the current store scope:

```blade
@block('your_block_identifier')
```

Optionally, you can specify a second argument with an array, which will be passed through to the [`strtr`](https://php.net/strtr) function to replace data within the block, for example:

```blade
@block('footer_links_block', [
    '<a' => '<a class="text-red-600"'
])
```

### `@content`

Processes content containing variables from Magento so that variables, blocks, and widgets are working.

```blade
@content($page->content)
```

Created your own variables? Have a look at the `content-variables` [configuration](configuration.md).

### `@widget`

Used to specify a widget location where widgets can be rendered.

```blade
@widget('location', 'type', 'handle', $entityId)
```

Have a look at the [current widget locations](https://github.com/rapidez/core/search?l=Blade\&q=widget) we've added by default and the widget tables in the database to see how the parameters work. Custom widgets can be defined with the `widgets` [configuration](configuration.md).

## Blade Components

Rapidez uses a separated package with Blade Components for inputs, checkboxes, buttons, etc. See: [rapidez/blade-components](https://github.com/rapidez/blade-components). An example of the input component:

```blade
<label>
    <x-rapidez::label>Something</x-rapidez::label>
    <x-rapidez::input name="something" class="extra-styling" />
</label>
```

Additionally, there are some Rapidez specific components within the core. See the [resources/views/components/](https://github.com/rapidez/core/tree/master/resources/views/components) directory.

::: tip
Try to use these elements as much as possible, so that if you'd like to change the appearance you can do so in only one place.
:::

### Listing component

The [`productlist`](https://github.com/rapidez/core/blob/master/resources/views/components/productlist.blade.php) component can be used to output a nice product list by SKU:

```blade
<x-rapidez::productlist :value="['MS04', 'MS05', 'MS09']"/>
```

Or with the product info from Javascript:

```blade
<x-rapidez::productlist
    value="config.productIds"
    field="entity_id"
    title="Products you need!"
/>
```

Rapidez is using this component to render the related products, up-sells, and cross-sells.

This [`productlist`](https://github.com/rapidez/core/blob/master/resources/views/components/productlist.blade.php) Blade component and the [`listing`](https://github.com/rapidez/core/blob/master/resources/views/components/listing.blade.php) Blade component (used for category pages and the search results page) are using the renderless [`Listing.vue`](https://github.com/rapidez/core/blob/master/resources/js/components/Listing/Listing.vue) component that has some useful props:

Prop | Type | Explanation
:--- | :--- | :---
`index` | String | The ElasticSearch/OpenSearch index name
`categoryId` | Number | Filter the items by category ID
`query` | Function: Array | Allows adding an array of queries to the query, inside the [query context](https://www.elastic.co/docs/explore-analyze/query-filter/languages/querydsl#query-context). This can be used to, for example, alter scoring of the documents. The resulting array from this gets placed directly inside of a `must` block in the query.
`baseFilters` | Function: Array | Allows adding an array of filters to the query, inside the [filter context](https://www.elastic.co/docs/explore-analyze/query-filter/languages/querydsl#filter-context). Note that the filter context cannot be used to alter scores, and instead should be used only to filter documents. The resulting array from this gets placed directly inside of a `filter` block in the query.
`filterQueryString` | String | The easiest way to filter, see [query string query](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-query-string-query). This gets transformed into a base filter (see above).
`configCallback` | Function | Can be used to change the config per listing

## Blade Icons

Rapidez comes preinstalled with [Blade Icons](https://blade-ui-kit.com/blade-icons?set=1), providing a massive library of icons you can use in your project! With many [icon packages available](https://github.com/blade-ui-kit/blade-icons#icon-packages) to get even more icons.

### Icon Deferring

We've added [Icon deferring](https://github.com/blade-ui-kit/blade-icons#deferring-icons) support to Blade Icons in order to reduce HTML element count when icons are used often. In Rapidez, this is enabled by default. If you would rather turn it off, you can change it globally in the options by publishing the config with:

```bash
php artisan vendor:publish --tag=blade-icons
```

And adding `'defer' => false` to the `'attributes'` section within the config file:

```php
...
'attributes' => [
    // 'width' => 50,
    // 'height' => 50,
    'defer' => false// [!code ++]
],
...
```

Or per icon:

```blade
<x-heroicon-s-heart class="h-6 w-6 text-red-600" :defer="false" />
```

## Vue Directives

On top of Vue, we've added some extra directives.

### `v-blur`

Just like [v-cloak](https://vuejs.org/api/built-in-directives.html#v-cloak), but instead of hiding, the element will be blurred. Useful if you don't like to have any layout shifts.

### `v-on-click-away`

Rapidez uses [vue-clickaway](https://github.com/simplesmiler/vue-clickaway), enabling you to close something if you click away from the element. [An example can be found within the core](https://github.com/search?q=repo%3Arapidez%2Fcore%20v-on-click-away\&type=code).

## Vue helpers

Rapidez includes the following Javascript helpers to manipulate your data and content:

| function | example output | description |
|---|---|---|
|`truncate(value, limit)`|Lorem ipsum dolor sit amet, c...|Truncates a string when it is longer than the limit length, then adding `...` at the end when necessary.|
|`price(value, extra)`|€ 24,99|Displays a price using Intl.NumberFormat with the current locale information. `extra` is optional and can be used for any extra parameters that should be passed into the formatter|
|`url(path)`|`https://demo.rapidez.io/joust-duffle-bag.html`|Ensures a url starts with the domain (by checking if it starts with a `/`)|
|`htmlDecode(input)`|`Tote <mark>bag</mark>`|Decodes any html characters (like `&lt;`).|
|`productPrice(product)`||Helper function that retrieves the current price of a product taking tier prices into account.|
|`productSpecialPrice(product)`||Helper function that retrieves the current special price of a product taking tier prices into account. Returns null if not relevant.|
|`roundCurrency(price)`||Rounds a price to the correct amount of decimals for the active currency.|
|`sumPrices(a, b)`||Sums two prices together, cutting off any excess decimals.|
|`stripHtmlTags(html, safeTags)`||Strips any HTML tags from a string except for the "safe" tags (and only without any attributes) using regex. safeTags defaults to `['mark']`.|

The following helpers are set on the global Vue object. Within javascript you may access them using the `window.app.config.globalProperties` object, inside of templates this is not necessary:

| name | description |
|---|---|
|`search(value)`|Redirects you to the search page with the given value as the search query, but only if the value is not empty.|
|`toggleScroll(bool)`|Sets the scroll lock on the page. If the `bool` parameter is not set, it will toggle.|
|`resizedPath(imagePath, size, store, sku)`|Returns a resized image URL. Can be used with a SKU instead of an image path if `sku` is set to true. `store` defaults to the current store.|
|`loggedIn`|Returns true only when the customer is logged in.|
|`hasCart`|Returns true only when there is an active cart.|
|`canOrder`|Returns true only when every item in the cart is available.|

## Multistore

Rapidez also has support for multiple themes! This is based on the `MAGE_RUN_CODE`.

### Blade

As mentioned in the [multistore configuration docs](configuration.md#multistore), it's possible to have different config files per store. To have a different theme per store, create or edit `/config/rapidez/stores/{store_code}/frontend.php` and define a custom path like so:

```php
<?php

return [
    'theme' => resource_path('themes/custom_theme'),
];
```

The structure of your theme folder will be the same as your views folder, so overriding the views folder is as simple as copying and pasting the file with the correct folder structure.

### Tailwind CSS

If you only want to change some Tailwind CSS colors and styling in your multistore and do not need to overwrite any templates, it may be a good idea to only use a different Tailwind CSS config. This can be done by editing your Vite config to generate different CSS files with different Tailwind CSS configs.

1. **`vite.config.js`**

```js
export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',// [!code --]
                'resources/css/app.<store_code>.css',// [!code ++]
                'resources/css/app.<another_store_code>.css',// [!code ++]
                'resources/js/app.js',
            ],
```

2. **`resources/css/app.<store_code>.css`**

```css
@import "./app.css";

/* Store specific styles */
```

3. **`resources/views/layouts/app.blade.php`**

```blade
@vite([
    'resources/css/app.css',// [!code --]
    'resources/css/app.' . config('rapidez.store_code') . '.css',// [!code ++]
    'resources/js/app.js'
])
```

Of course, you can do this any way you want if you want to load the same CSS for specific stores. Map the store code to a theme name and use that as your CSS file.

## Translations

You can create a JSON file for your language within the `lang` directory, for example: `/lang/de.json`. As an example, have a look at the [existing translations in the core](https://github.com/rapidez/core/tree/master/lang). For more information, read the [Laravel Localization docs](https://laravel.com/docs/12.x/localization).

In the core, we also have a `frontend.php` translation file per language. These translations will be available from Javascript with: `config.translations.key`. To publish them to your project, use:

```bash
php artisan vendor:publish --provider="Rapidez\Core\RapidezServiceProvider" --tag=rapidez-translations
```

---

---
url: /5.x/extending.md
description: Adding models, controllers, widgets, routes and extending the autocomplete.
---

# Extending

***

\[\[toc]]

## Models

All models are defined in the [Rapidez config](configuration.md#rapidez):

```php
'models' => [
    'page'         => Rapidez\Core\Models\Page::class,
    'attribute'    => Rapidez\Core\Models\Attribute::class,
    'product'      => Rapidez\Core\Models\Product::class,
    ...
]
```

To overwrite a model, you can simply extend it. For example, create a new `app/Models/Product.php` file and extend the Rapidez model:

```php
<?php

namespace App\Models;

use Rapidez\Core\Models\Product as BaseProduct;

class Product extends BaseProduct {
    //
}
```

And change it in the configuration file:

```php
'models' => [
    ...
    'product'      => Rapidez\Core\Models\Product::class,// [!code --]
    'product'      => App\Models\Product::class,// [!code ++]
    ...
]
```

## Controllers

All controllers are defined in the [Rapidez config](configuration.md#rapidez):

```php
'controllers' => [
    'page'     => Rapidez\Core\Http\Controllers\PageController::class,
    'product'  => Rapidez\Core\Http\Controllers\ProductController::class,
    'category' => Rapidez\Core\Http\Controllers\CategoryController::class,
],
```

For controllers, you can also extend them, for example: `app/Controllers/ProductController.php`. Make sure you implement the methods as defined in the core controller and define it in the configuration just like you would with models.

## Widgets

Magento widgets can be defined in the [Rapidez config](configuration.md#rapidez):

```php
'widgets' => [
    'Magento\Cms\Block\Widget\Block'                   => Rapidez\Core\Widgets\Block::class,
    'Magento\CatalogWidget\Block\Product\ProductsList' => Rapidez\Core\Widgets\ProductList::class,
    'Magento\Catalog\Block\Category\Widget\Link'       => Rapidez\Core\Widgets\ProductAndCategoryLink::class,
    'Magento\Catalog\Block\Product\Widget\Link'        => Rapidez\Core\Widgets\ProductAndCategoryLink::class,
    'Magento\Cms\Block\Widget\Page\Link'               => Rapidez\Core\Widgets\PageLink::class,
],
```

They are rendered with the [widget directive](theming.md#widget). You can implement additional widgets by adding them to the configuration and creating a class. All parameters will be added to the constructor, and a `render()` method should return the output. Take a look at the [existing widgets](https://github.com/rapidez/core/tree/master/src/Widgets).

If the widget doesn't need any extra logic and just needs a view with the available parameters, you can simply specify the view name. All parameters will be available within the `$options` variable.

```php
'widgets' => [
    ...
    'Your\Custom\Widget' => 'viewname',
],
```

::: tip Alternatives to Magento's CMS functionalities
Take a look at the [CMS packages](packages.md#cms)!
:::

## Routes

You can add any additional routes just "the Laravel way". Check out the [Laravel routing docs](https://laravel.com/docs/12.x/routing). Additionally, Rapidez adds a handy `store_code` route middleware, so you can create routes for specific stores:

```php
Route::middleware('store_code:YOUR_STORE_CODE')->get('customroute', function () {
    // 
});
```

Alternatively, you can create a custom routes file if you have multiple routes specific to a store within `bootstrap/app.php`:

```php
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
    then: function () { // [!code focus]
        Route::middleware(['web', 'store_code:YOUR_STORE_CODE']) // [!code focus]
            ->group(base_path('routes/YOUR_STORE_CODE.php')); // [!code focus]
    }, // [!code focus]
)
```

Rapidez also adds a useful token guard for authenticated customers, called `magento-customer`. You can use this to create routes that require logging in:

```php
Route::middleware('auth:magento-customer')->get('customroute', function () {
    // 
});
```

## Autocomplete

The autocomplete can contain as many Elasticsearch/OpenSearch indexes as you wish. You can add these in the `frontend.php` config file. For example:

```php
'autocomplete' => [
    'additionals' => [
        'history'    => [],
        'categories' => [],

        'blogs' => [ // [!code focus]
            'size' => 10, // [!code focus]
        ], // [!code focus]
    ],

    'size' => 3,
],
```

### Configuration

There are two ways to define a new additional index. The shorthand way is by only giving the index name, like so:

```php
'categories' => [],
```

Alternatively, you can have more control by expanding the configuration like below:

```php
'blogs' => [
    'size' => 10,
],
```

| Option | Required | Description |
|---|---|---|
| `size` | No | Overrides the default `size` parameter for this index, letting you define a different page size for this specific index. In the above example, we only get a maximum of 10 blogs to be shown in the autocomplete instead of the default 3. |

### Displaying new indexes

When you add a new index to this configuration, Rapidez will attempt to include `rapidez::layouts.partials.header.autocomplete.index_name_here` in the autocomplete. This means that any additional indexes should have their own view defined under

```
/resources/views/vendor/rapidez/layouts/partials/header/autocomplete/index_name_here.blade.php
```

You could use the [categories view](https://github.com/rapidez/core/blob/master/resources/views/layouts/partials/header/autocomplete/categories.blade.php) as an example.

---

---
url: /5.x/testing.md
description: >-
  Everything about testing with Rapidez with PHPUnit, Playwright, Static
  analysis and Continuous Integration
---

# Testing

***

Rapidez is built upon [Laravel](https://laravel.com/), so you have access to its [testing suite](https://laravel.com/docs/12.x/testing). On top of that there is a full [Playwright](https://playwright.dev/) test suite available!

\[\[toc]]

## Installation

Rapidez already includes some tests in the core. To install and to use these tests, you can run the following command. This will publish all the tests to your project.

```bash
php artisan rapidez:install:tests
```

## Running tests

* PHPUnit: `vendor/bin/phpunit` (feature tests)
* Playwright: `npx playwright test --ui` (browser tests)

## Writing tests

All tests are located in the `/tests` folder:

* `/tests/playwright` -> [Laravel testing docs](https://laravel.com/docs/12.x/testing)
* `/tests/Feature` -> [Playwright docs](https://playwright.dev/docs/intro)

## Static analysis

Rapidez comes with [PHPStan](https://phpstan.org/) for static analysis and [Laravel Pint](https://laravel.com/docs/12.x/pint) for code style analysis. These can be used in to keep the code quality high. The available commands:

* PHPStan: `composer analyse`
* Pint test: `composer style`
* Pint fix: `composer fix-style`

## Continuous Integration

Have a look at the [Github workflows within the Rapidez Core](https://github.com/rapidez/core/tree/master/.github/workflows). Need help? For example with running it on another platform like Bitbucket Pipelines? Or, to run the tests with your Magento environment instead of a demo environment in Docker? [Ask us on Slack!](https://rapidez.io/slack)

---

---
url: /5.x/graphql-components.md
description: >-
  Everything about the Rapidez `<graphql>` and `<graphql-mutation>` renderless
  Vue components.
---

# GraphQL

***

Magento has an excellent [GraphQL](https://devdocs.magento.com/guides/v2.4/graphql/) implementation which gives you more flexibility over the [REST API](https://devdocs.magento.com/guides/v2.4/rest/bk-rest.html). Rapidez provides some handy renderless GraphQL Vue components to communicate with GraphQL.

::: tip Examples
See the usage within the [Rapidez Repositories](https://github.com/search?q=org%3Arapidez+graphql+language%3ABlade\&type=code\&l=Blade)
:::

\[\[toc]]

## Query

`<graphql>` component example to get a list of available countries from Magento:

```html
<graphql v-cloak query="{ countries { full_name_locale } }">
    <ul v-if="data" slot-scope="{ data }">
        <li v-for="country in data.countries">@{{ country.full_name_locale }}</li>                
    </ul>
</graphql>
```

### Props

Prop | Type | Default | Explanation
:--- | :--- | :--- | :---
`query` | String | Required | GraphQL query
`variables` | Object | `{}` | GraphQL variables
`store` | String | `window.config.store_code` | Store code
[`group`](#grouping) | String | | Bundle queries by a name into 1 request [see: group](#grouping)
`check` | Function | | Run a check on the response data, for example: `check="(data) => data.countries[0] == 'Country'"`
`redirect` | String | | Where to redirect if the check fails
`cache` | String | | Cache key in localstorage. Caches only when provided and will be prefixed with `graphql_`. Flushes when the [cache](cache.md) is cleared.
`callback` | Function | | Called after the query
`error-callback` | Function | Notification | Called after an unsuccessful query

::: tip
With large GraphQL queries you can extract the query to a separated file, for example: `resources/views/queries/countries.graphql` and include it with: `query='@include('queries.countries')'`
:::

### Slot scopes

Prop | Type | Explanation
:--- | :--- | :---
`data` | Object | The data returned from the GraphQL request
`running` | Boolean | True when running
`runQuery` | Function | Run the query again

## Mutation

`<graphql-mutation>` component example with a newsletter subscription form:

```html
<graphql-mutation v-cloak query="mutation visitor ($email: String!) { subscribeEmailToNewsletter(email: $email) { status } }" :alert="false" :clear="true">
    <div slot-scope="{ mutate, variables, mutated, error }">
        <strong v-if="mutated">
            @lang('Thank you for subscribing!')
        </strong>
        <div v-else>
            <form v-on:submit.prevent="mutate">
                <x-rapidez::input name="email" type="email" v-model="variables.email"/>
                <x-rapidez::button type="submit">
                    @lang('Subscribe')
                </x-rapidez::button>
            </form>
            <p v-if="error">
                @{{ error }}
            </p>
        </div>
    </div>
</graphql-mutation>
```

### Props

Prop | Type | Default | Explanation
:--- | :--- | :--- | :---
`query` | String | Required | The GraphQL query
`variables` | Object | `{}` | Set the default variables `:variables="{ email: 'example@rapidez.io' }"`, useful when having the mutation component within the [`<graphql>`](graphql-components.md#query) component
`store` | String | `window.config.store_code` | Store code
[`group`](#grouping) | String | | Bundle queries by a name into 1 request [see: group](#grouping)
`watch` | Boolean | `true` | Should the `variables` be watched?
`redirect` | String | | The redirect URL
`alert` | Boolean | `true` | Show an alert when an error occurs
`clear` | Boolean | `false` | Clear the values after the mutation
`notify` | Object | | Success notification
`before-request` | Function(query, variables, options): \[query, variables, options] | | Called before the request is sent in order to change, must return `[query, variables, options]` if used
`callback` | Function | | Called after the mutation
`error-callback` | Function | | Called after an unsuccessful query
`mutate-event` | String | | Event name to listen to, used to trigger the mutate method
`recaptcha` | Boolean | `false` | Sends the `X-ReCaptcha` header with the request

### Slot scopes

Slot scopes are useful when wanting to get or update values or functions within the component's template.

Prop | Type | Explanation
:--- | :--- | :---
`mutate` | Function | Run the GraphQL query
`mutated` | Boolean | True if the mutation has run
`mutating` | Boolean | True when mutating (Alias of `running`)
`running` | Boolean | True when running
`error` | String | The error message if the GraphQL request failed
`variables` | Object | GraphQL variables
`watch` | Boolean | Can be used to toggle the `watch` prop

## Grouping

With the `group` prop, you are able to bundle multiple GraphQL requests into 1 to increase performance. When one of them gets executed, the combined query will be sent.

::: warning Note
You cannot combine mutations and queries. Variable names should be unique, except `cart_id`
:::

We also provide a `submitPartials()` helper which can be used to submit multiple queries and have a callback when they're all finished. This is used in the onestep checkout to submit each section and only continue to the success page when everything is finished.

```html
<form v-on:sumbit.prevent="(e) => {
    submitPartials(e.target?.form ?? e.target)
        .then((result) => window.Turbo.visit('/success'))
        .catch(() => {})
}">
    <graphql ...>
        <fieldset partial-submit v-on:partial-submit="(e) => mutate().then(e.detail.resolve).catch(e.detail.reject)">...</fieldset>
    </graphql>
    <graphql ...>
        <fieldset partial-submit v-on:partial-submit="(e) => mutate().then(e.detail.resolve).catch(e.detail.reject)">...</fieldset>
    </graphql>
    <button type="submit">Save</button>
</form>
```

---

---
url: /5.x/package-development.md
description: >-
  How to develop packages for Rapidez with info about Eventy filters, Vue
  events, Javascript events, fallback routing, extending models and
  notifications.
---

# Packages

***

This works just like any Laravel package, [read their documentation to get started](https://laravel.com/docs/12.x/packages) and have a look at the [existing packages](packages.md) to see how things are handled. You could use our [Package Template](https://github.com/rapidez/package-template) as a starting point.

\[\[toc]]

## Eventy Filters

[Eventy](https://github.com/tormjens/eventy) is used to have WordPress style filters which can be used within packages. Have a look at [their docs](https://github.com/tormjens/eventy#filters) to see how these filters can be used. Examples can also be found within existing Rapidez packages, for example within the [`AmastyLabelServiceProvider.php`](https://github.com/rapidez/amasty-label/blob/master/src/AmastyLabelServiceProvider.php) from the [Rapidez Amasty Label](https://github.com/rapidez/amasty-label) package.

Filter | Explanation
:--- | :---
`*.scopes` | Add additional global scopes to every model available e.g. `product.scopes` or `category.scopes`
`product.casts` | Add additional global product casts
`product.child.scopes` | Add product scopes to the product query when indexing
`productpage.scopes` | Add product scopes only for the product page
`productpage.frontend.attributes` | Add product attributes to the frontend
`quote.items.select` | Manipulate the quote items select query
`index.product.scopes` | Add product scopes to the product query when indexing
`index.product.attributes` | Index additional product attributes
`index.*.data` | Manipulate the model's data before it gets indexed, e.g. `index.product.data`
`index.*.mapping` | Manipulate the index mapping for a given model, e.g. `index.product.mapping`
`index.*.settings` | Manipulate the index settings for a given model, e.g. `index.product.settings`
`index.*.synonym-fields` | Manipulate the fields that allow for synonyms on a given model, e.g. `index.product.synonym-fields`
`routes` | ([deprecated](#addfallbackroute)) Register additional routes ([example](https://github.com/rapidez/amasty-shop-by-brand/blob/master/src/AmastyShopByBrandServiceProvider.php))

Every model extends the [base model](https://github.com/rapidez/core/blob/master/src/Models/Model.php) which uses the [`HasEventyGlobalScopeFilter` trait](https://github.com/rapidez/core/blob/master/src/Models/Traits/HasEventyGlobalScopeFilter.php) so it's possible to add scopes to every model, for example: `category.scopes`

## Vue Events

Rapidez emits some custom Vue events you can hook into with [`on()`](https://github.com/rapidez/core/blob/master/resources/js/polyfills/emit.js). This is used for example within the [Rapidez GTM](https://github.com/rapidez/gtm) package, have a look at the [`gtm.js`](https://github.com/rapidez/gtm/blob/master/resources/js/gtm.js) file.

Event | Explanation
:--- | :---
`registered` | After registering the user, contains any information passed except for the password
`logged-in` | After the user has logged in
`logout` | After the user attempts to log out, listen to this to clear any sensitive information about the user
`logged-out` | After the user has been logged out
`cart-add` | After a product has been added to the cart
`cart-refreshed` | After the cart is refreshed
`cart-remove` | When the remove from cart button has been used
`checkout-credentials-saved` | After the checkout credentials are saved
`checkout-payment-selected` | After the payment method has been selected
`checkout-success` | When the user is on the success page
`checkout-payment-saved` | After the payment method is saved
`product-super-attribute-change` | After a swatch change, when calling this the product image updates based on the choice
`postcode-change` | Events for postcode integrations, fired after postcode or housenumber changed.
`vat-change` | Events for VAT validation.

## Regular Events

These are custom vanilla JS events that are fired that you can hook into:

Event | Explanation
:--- | :---
`vue:loaded` | After `window.app` has been created, always use this if you want to interact with the global Vue object after it's created. `DOMContentLoaded` or `turbo:load` are NOT recommended for this.
`vue:mounted` | After the global vue component has been mounted, [see](https://github.com/rapidez/core/blob/master/resources/js/package.js#L173)
`turbo:load` | The `DOMContentLoaded` for Turbo navigation, it will fire late the initial request. We recommend using `vue:loaded` instead. There are more [Turbo events](https://turbo.hotwired.dev/reference/events)
`cart-updated` | Fired whenever the `updateCart` has been executed, this is no guarantee data has actually changed.
`insights-event:*` | These are fired by the listing and autocomplete component. `*` needs to be replaced by any of the [InsightsMethods](https://github.com/algolia/instantsearch/blob/5a2d2121c1f82840e59ba69edfe0a4f41450f41b/packages/instantsearch.js/src/types/insights.ts#L21). In the event detail you will get the [InsightsEvent](https://github.com/algolia/instantsearch/blob/5a2d2121c1f82840e59ba69edfe0a4f41450f41b/packages/instantsearch.js/src/types/insights.ts#L34) and can be used for analytics.

## Fallback routing

If your package cannot define its own predefined routes you will want to start using fallback routes to check if it matches a route in e.g. your database.

### `Rapidez::addFallbackRoute()`

::: info Why?
If you use the `Route::fallback()` you'll prevent other packages from implementing fallback routes, this is what we've created `Rapidez::addFallbackRoute()` for.
:::

You can pass controllers, functions, etc. in the same way like you would with `Route::fallback()` however it will check each fallback route until it finds one that does not return void or a 404. You can use this function anywhere so long as it's before the fallback route is triggered, we suggest in your ServiceProvider or Routes file ([example](https://github.com/rapidez/core/blob/aa1dbb54faed244b982f5b6198749ccf493c210a/src/RapidezServiceProvider.php#L87)).

The first argument to this function will be your Callable or action, the second argument will be the position or priority it has. Lower means higher priority, but it is optional.

::: tip
If your check to see if it matches has a high performance impact (for example when it's an API request), consider putting the position higher than `9999` and caching the results.
:::

Examples:

```php
use Rapidez\Core\Facades\Rapidez;

Rapidez::addFallbackRoute(UrlRewriteController::class);
Rapidez::addFallbackRoute('UrlRewriteController@index');
Rapidez::addFallbackRoute([UrlRewriteController::class, 'index'], 5);
Rapidez::addFallbackRoute(function (Request $request) {return redirect('/');}, 5);
```

## Hooking into commands

You can hook into commands by using the events that Rapidez fires. See [all available events](https://github.com/rapidez/core/tree/master/src/Events). For example, if you want to fire a command that runs before the indexer, you can put the following into your `AppServiceProvider.php`:

```php
Event::listen(IndexBeforeEvent::class, fn($event) => $event->context->call('another:command'));
```

## Extending Models

All Rapidez models extend the [base model](https://github.com/rapidez/core/blob/master/src/Models/Model.php). This means it implements [Macroable](https://laravel.com/api/master/Illuminate/Support/Traits/Macroable.html), making it possible to add your own functions without overwriting the model itself!

### Adding a single function

Say you want to add a single function to the Product model, then you can add the following in your ServiceProvider boot method:

```php
Product::macro('myTestFunction', function () {
    return 'completed!';
});
```

### Adding multiple functions

If you want to add multiple functions, this might get cluttered. In that case, you can use a mixin. All functions defined in there will be made available from your model:

```php
Product::mixin(ProductMixin::class);
```

### Adding Relationships

Your package might add a new model that should be accessible from a Rapidez model. Relationships can be added with:

```php
Product::resolveRelationUsing(
    'testRelation',
    fn (Product $product) => $product->hasMany(MyTestModel::class, 'product_id');
);
```

## Notifications

If you'd like to show a notification after a redirect from a custom controller you can use:

```php
return redirect('/')->with(['notification' => [
    'message' => 'Lorem ipsum dolor sit amet',
    'type' => 'success',
]]);
```

By default, there are 4 types: `info`, `success`, `warning`, and `error`. The style differences are defined in the [frontend config](https://github.com/rapidez/core/blob/master/config/rapidez/frontend.php), everything else is in the [Blade template](https://github.com/rapidez/core/blob/master/resources/views/components/notifications.blade.php).

---

---
url: /5.x/ai.md
description: >-
  Everything you need to know when you want to use AI / Laravel Boost with
  Rapidez.
---

# Artificial Intelligence

***

Do you want to build your next webshop with AI? Most of the AI agents around know what Rapidez is and how it works, but you can help them with these instructions.

\[\[toc]]

## Laravel Boost

> Laravel Boost accelerates AI-assisted development by providing the essential guidelines and agent skills that help AI agents write high-quality Laravel applications that adhere to Laravel best practices.

Just follow the installation instructions in the [Laravel Boost docs](https://laravel.com/docs/boost). Rapidez packages include additional instructions which will be discovered by Laravel Boost automatically.

## Docs

AI agents can read these docs easier with `llms.txt` files. For the latest Rapidez version:

* https://docs.rapidez.io/llms.txt
* https://docs.rapidez.io/llms-full.txt

Or version specific:

* https://docs.rapidez.io/5.x/llms.txt
* https://docs.rapidez.io/5.x/llms-full.txt

::: tip FYI
With Laravel Boost installed the Rapidez docs will be discovered and used automatically!
:::

## Updates

Are you updating from Rapidez 4.x to 5.x? We do have a [prompt in the upgrade docs](upgrading.md#using-ai) which can help you to let AI do the upgrade automatically.

---

---
url: /5.x/indexer.md
description: >-
  The Rapidez indexer containing product and category information using Laravel
  Scout and Elasticsearch/OpenSearch index for InstantSearch. Everything about
  reindexing and extending the indexer.
---

# Indexer

***

The indexer adds the product and category information with [Laravel Scout](https://laravel.com/docs/12.x/scout) to an Elasticsearch/OpenSearch index for InstantSearch. There are multiple ways to refresh the index:

\[\[toc]]

## Manually

To do a full (re)index run this command from your terminal:

```bash
php artisan rapidez:index
```

::: warning
The default chunk size for indexing is 500 products. If you have a lot of attributes and/or children on your products, you may run into out-of-memory issues during indexing. You can change the chunk size in the scout configuration file `config/scout.php`. It is **not** recommended to set this to very low number. If you're having memory issues, a chunk size of 100 should usually suffice.
:::

This will reindex everything for all stores. With the `--store` and `--types` options you can be more specific, see: `php artisan rapidez:index --help`. Alternatively there is also:

```bash
php artisan rapidez:index:update
```

This will only update changed items since the last index based on the "updated at" column set on the model. This command will not remove anything from the index!

## Scheduler

Instead of manually triggering the index you can simply schedule these commands within the console routes file: `routes/console.php`. For more information, see [Task Scheduling](https://laravel.com/docs/12.x/scheduling)

```php
Schedule::command('rapidez:index')->hourly();
Schedule::command('rapidez:index:update')->everyMinute()->withoutOverlapping();
```

## Webhook

### Partial index

If you'd like to have even faster updates we provide an endpoint to trigger updates:

```
/api/admin/index/MODEL?token=RAPIDEZ_TOKEN
```

Replace `MODEL` with the name from the [models config](https://github.com/rapidez/core/blob/master/config/rapidez/models.php), most likely `product`, `category` or maybe a custom model you've created like `blog`. The `RAPIDEZ_TOKEN` comes from your `.env`. If you do a `POST` request it will add / update an item and a `DELETE` request will remove an item from the index. The accepted parameters:

| Param    | Required | Data  |
| -------- | -------- | ----- |
| `ids`    | Yes      | Array of items ID's; `[1, 2, 3]` |
| `stores` | No       | - Default is the current store- For all stores use `*`- Specific stores: `['store_code1', 'store_code2']` |

::: tip Magento Webhooks
Magento doesn't provide any webhooks by default, but you could use something like [mageplaza/magento-2-webhook](https://github.com/mageplaza/magento-2-webhook) and configure it to reindex on product and category updates.
:::

### Full reindex

Additionally there is an endpoint that triggers a full reindex with just a `GET` request:

```
/api/admin/index/products?token=RAPIDEZ_TOKEN
```

This uses [`fastcgi_finish_request()`](https://www.php.net/fastcgi_finish_request), which means you get a response immediately while the index process continues in the background.

## Extending

### Adding models

The Rapidez indexer listens to the [Searchable trait](https://github.com/rapidez/core/blob/master/src/Models/Traits/Searchable.php), so if you want your own models indexed you can simply implement the trait and add it to the [models config](extending.md#models). By default this will index everything arrayable in an index following:

```
SCOUT_PREFIX _ plural model name _ STORE_ID
```

Make sure any custom eloquent models extend Rapidez's [base model](https://github.com/rapidez/core/blob/master/src/Models/Model.php).

::: tip Scout Docs
For more advanced usage take a look at the [Scout Docs](https://laravel.com/docs/12.x/scout)
:::

### Mapping & settings

You can define custom index mapping and settings for each searchable model. You can do this in a few different ways:

#### Model

On the searchable model itself, you can define the following functions:

```php
protected static function indexMapping(): array
{
    // return [
    //     'properties' => [
    //         'children' => [
    //             'type' => 'flattened',
    //         ],
    //     ],
    // ];
}

protected static function indexSettings(): array
{
    // return your settings here
}
```

#### Eventy

See the [package development docs](package-development.md#eventy-filters) for more information on Eventy.

##### Array

You can also hook into the Eventy filters to directly alter the mapping before it gets sent to ElasticSearch/OpenSearch. This is useful for when you want to alter your mapping or settings within a serviceprovider. The filter names for this are `index.*.mapping` and `index.*.settings` where the `*` represents the model name (or its custom `$modelName`). For example:

```php
Eventy::addFilter('index.category.mapping', fn ($mapping) => array_merge_recursive($mapping, [
    'properties' => [
        'children' => [
            'type' => 'flattened',
        ],
    ],
]));
```

##### Class

You can also use classes instead of directly altering the arrays within your filter. For an example of this, have a look at [the `withSynonyms` class](https://github.com/rapidez/core/blob/master/src/Index/WithSynonyms.php). Example:

```php
// Simple without parameters
Eventy::addFilter('index.product.settings', fn ($filters) => array_merge($filters ?: [], [WithSynonyms::class]));

// With parameters
Eventy::addFilter('index.product.mapping', fn ($filters) => array_merge($filters ?: [], [
    [WithSynonyms::class, 'fields' => $productSynonymFields]
]));
```

---

---
url: /5.x/cache.md
description: How caching works, can be used and cleared with Rapidez.
---

# Cache

***

Rapidez caches certain things to improve speed. It also provides some options to improve the speed even more! 🚀

\[\[toc]]

## Invalidation

After you have made changes to some Magento configuration, you need to clear the cache. This can be easily done by running the command `php artisan cache:clear` from the terminal. However, you can also automate this process just like with the [indexer](indexer.md#webhook) by using the cache clear URL `/api/admin/cache/clear?token=` and appending your token.

::: tip
To disable the cache while developing, change the `CACHE_DRIVER` in the `.env` file to `null`.
:::

## Partial caching

When you have a template consuming too much time or resources and it doesn't have to do that every time, you could use [`@includeCached()`](https://github.com/rapidez/blade-directives#includecached) to cache the partial.

## Full page caching

Rapidez performs well out-of-the-box, but if you'd like to reduce the first load even more, you could add full page caching.

If you're using the [Statamic integration](packages/statamic.md), we recommend using their [static caching](packages/statamic.md#static-caching) as it supports [multiple caching strategies](https://statamic.dev/static-caching#caching-strategies), and invalidation comes with the package.

Alternatively, you could implement one of these packages with different strategies:

* [spatie/laravel-responsecache](https://github.com/spatie/laravel-responsecache)
* [JosephSilber/page-cache](https://github.com/JosephSilber/page-cache)
* [spatie/laravel-varnish](https://github.com/spatie/laravel-varnish)

### Uncacheable

To prevent a response from getting cached you should add the `uncacheable` middleware, or pass it through the `uncacheable.response` filter:

```php
$response = Eventy::filter('uncacheable.response', $response);
```

### Cloudflare

Using [Cloudflare's CDN edge](https://www.cloudflare.com/learning/cdn/glossary/edge-server/) you can speed up page responses even more (~30ms) by bringing the files closer to your customers. By default Cloudflare will not cache any pages, but you can configure it by [creating a cache rule in Cloudflare](https://developers.cloudflare.com/cache/how-to/cache-rules/create-dashboard/) with these settings:

* [Cache eligibility](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/#cache-eligibility)
  * [Eligible for cache](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/#eligible-for-cache-settings)
* [Edge TTL](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/#edge-ttl)
  * `Use cache-control header if present, bypass cache if not` - this ensures Cloudflare will not cache pages that don't explicitly state they can be cached
* [Browser TTL](https://developers.cloudflare.com/cache/how-to/cache-rules/settings/#browser-ttl)
  * `Respect origin TTL`

With this Cloudflare will listen to the cache-control headers sent by your server, but by default Laravel and Rapidez will make each page response private, so no caching will be done. If you're sure your pages contain no private data (which is the case by default in Rapidez) you can add the [Cache Control Middleware](https://laravel.com/docs/master/responses#cache-control-middleware). These packages control it for you:

* [spatie/laravel-varnish](https://github.com/spatie/laravel-varnish)
* [rapidez/statamic](packages/statamic.md) (see [Static Caching](packages/statamic.md#static-caching))

::: tip
You can use this package to make sure caches purged in Statamic also get purged in Cloudflare: [justbetter/statamic-cloudflare-purge](https://github.com/justbetter/statamic-cloudflare-purge).
:::

---

---
url: /5.x/turbo.md
description: Rapidez is using Turbo, but you can make things even faster with Turbo Frames.
---

# Turbo

***

[Turbo](https://turbo.hotwired.dev/) [Drive](https://turbo.hotwired.dev/handbook/drive) is used to accelerate navigation between pages by intercepting navigations, loading content via AJAX negating the need for full page reloads.

\[\[toc]]

## Turbo Frames

[Turbo Frames](https://turbo.hotwired.dev/handbook/frames) makes it possible to load parts of a page via AJAX. This could also be used to reduce the initial DOM size, for example by loading the content of a mega menu with it when the menu opens. Note that Vue doesn't normally work within the `<turbo-frame>` component; for this purpose we've made a `<vue-turbo-frame>` Vue component.

### Usage

The component works similarly to a regular `<turbo-frame>`, but includes pre-configured performance optimizations. An example with a menu that loads fully when it's visible within the browser:

```html
<vue-turbo-frame src="/menu-with-submenus" id="menu">
    <ul>
        <li>Just the top level menu items</li>
        <li>Those which should be visible directly</li>
    </ul>
</vue-turbo-frame>
```

And the route that is just serving a Blade template:

```php
Route::view('/menu-with-submenus', 'turbo-frames.menu');
```

And the `resources/views/turbo-frames/menu.blade.php` content:

```html
<turbo-frame id="menu">
    <ul>
        <li>Just the mega menu top level items
            <ul>
                <li>But now with all sub levels</li>
            </ul>
        </li>
        <li>Those which should be visible directly
            <any-vue-component>
                Vue Components do work!
            </any-vue-component>
        </li>
    </ul>
</turbo-frame>
```

***

Another example where the whole menu is behind a toggle:

```html
<details>
    <summary>Menu</summary>
    <vue-turbo-frame id="menu" src="/menu-with-submenus">
        Loading...
    </vue-turbo-frame>
</details>
```

### Default attributes

The component adds these defaults:

| Attribute | Value | Description |
|------|-------|-------------|
| `loading` | `lazy` | Content only loads when it scrolls into view, improving initial page load performance |
| `target` | `_top` | Ensures links navigate the whole page instead of staying within the frame |

---

---
url: /5.x/packages.md
description: >-
  A list of all Rapidez packages, but for most things Laravel packages can be
  used, and if Statamic is installed, Statamic addons can be used too.
---

# Packages

***

In addition to the Rapidez Core, we've created some packages listed here. They're just Laravel packages, see: [package development](package-development.md).

::: tip Laravel packages
All Laravel packages can be used with Rapidez, [that's 50,000+ packages available!](https://packagist.org/search/?query=laravel)
:::

::: tip Use a proper CMS
Magento isn't a CMS! We recommend [Statamic](https://statamic.com/) ([with our Statamic integration](packages/statamic.md)) so you can just configure some collections for pages, blogs, FAQs, etc with a really good block-based editor. Also configure your navigations and forms in your CMS.
:::

\[\[toc]]

::: tip Created a package?
[Edit this page](https://github.com/rapidez/docs/edit/master/src/5.x/packages.md) and add yours!
:::

## Base

Installed by default but can be removed or replaced with other packages.

* [Menu](https://github.com/rapidez/menu)
* [Account](https://github.com/rapidez/account)
* [Image Resizer](https://github.com/rapidez/image-resizer)

## Optional

Core Magento functionality but not installed by default.

* [Compare](https://github.com/rapidez/compare)
* [Reviews](https://github.com/rapidez/reviews)
* [Wishlist](#wishlists)
* [Product alerts](https://github.com/rapidez/product-alert)
* [Login As Customer](https://github.com/rapidez/login-as-customer)
* [MSI](https://github.com/rapidez/msi)

## Account

* [Custom Reorder](https://github.com/rapidez/custom-reorder)
* [Quick Order](https://github.com/rapidez/quick-order)

## Checkout

Opinionated checkout packages.

* [Checkout Theme](https://github.com/rapidez/checkout-theme/)
* [Confira](https://github.com/rapidez/confira)

## Payment providers

* [Mollie](https://github.com/rapidez/mollie)
* [Pay.nl](https://github.com/rapidez/paynl)
* [MultiSafepay](https://github.com/rapidez/multisafepay)
* [Riverty](https://github.com/rapidez/riverty)

## CMS

* [Strapi](https://github.com/rapidez/strapi)
* [Statamic](https://github.com/rapidez/statamic)

## Marketing

* [Google Tag Manager](https://github.com/rapidez/gtm)

## Monitoring

* [OpenReplay](https://github.com/rapidez/openreplay)
* [Sentry](https://github.com/rapidez/sentry)

## Social Login

* [Social login](https://github.com/rapidez/social-login)

## Wishlists

* [Default](https://github.com/rapidez/wishlist)
* [Guest Wishlist](https://github.com/rapidez/guest-wishlist)
* [Multiple Wishlists](https://github.com/rapidez/multiple-wishlists)

## Zipcode providers

* [Postcode.nl](https://github.com/rapidez/experius-postcode-nl)
* [Postcodeservice](https://github.com/rapidez/postcodeservice)
* [Pro6pp](https://github.com/rapidez/pro6pp-postcode)

## Vendors

Some Magento modules work out of the box, but most of the modules that do something on the frontend need to be integrated with Rapidez. Check the [package development docs](package-development.md).

### Amasty

* [Automatic Related Products](https://github.com/rapidez/amasty-automatic-related-products)
* [Labels](https://github.com/rapidez/amasty-label)
* [Promo Banners](https://github.com/rapidez/amasty-promo-banners)
* [Shop By Brand](https://github.com/rapidez/amasty-shop-by-brand)
* [Custom Form](https://github.com/rapidez/amasty-custom-form)

### Boldcommerce

* [Order comments](https://github.com/rapidez/boldcommerce-order-comments)

### Elgentos

* [Serverside Analytics](https://github.com/rapidez/elgentos-serverside-analytics)

### Mageplaza

* [Blog](https://github.com/rapidez/mageplaza-blog)

### MagePrince

* [FAQ](https://github.com/rapidez/mageprince-faq)

### Mirasvit

* [Advanced Seo Suite](https://github.com/rapidez/mirasvit-advanced-seo-suite)
* [Knowledge Base](https://github.com/rapidez/mirasvit-knowledge-base)
* [Labels](https://github.com/rapidez/mirasvit-label)

### Snowdog

* [Menu](https://github.com/rapidez/snowdog-menu)

### Smile

* [Store Locator](https://github.com/rapidez/smile-store-locator)

---

---
url: /5.x/packages/statamic.md
---
# Statamic

***

The Rapidez with [Statamic](https://statamic.com/) integration! 🤝🚀

::: info Version 8
This documentation is for [`rapidez/statamic`](https://github.com/rapidez/statamic) `^8.0`, which requires PHP 8.4 and [Statamic 6](https://statamic.dev/).
:::

\[\[toc]]

## Features

* Products, categories, and read-only product attributes (plus attribute options) are integrated through [Runway](https://github.com/statamic-rad-pack/runway)
* Brand landing pages use a regular Statamic collection named `brands` (with page builder and SEO) that is linked to the Runway resource, which is unlike other Runway resources. The Runway resource itself is hidden.
* Automatic site registration based on Magento stores
* Routing: Statamic routes are the fallback
* Page builder fieldset with multiple components:
  * Product slider
  * Content
  * Image
  * Form
* Navigation component
* Responsive images with [Glide](https://github.com/justbetter/statamic-glide-directive)
* Breadcrumbs on pages
* Globals available in all views
* SEO meta title and description
* Automatic alternate hreflang link tags
* Sitemap for all sites, collections, and taxonomies

## Installation

1. **Install Statamic with the Rapidez Statamic integration**

```bash
composer require rapidez/statamic
```

2. **Run the install command**

```bash
php artisan rapidez-statamic:install
```

And follow the steps. When finished visit `/cp` for the control panel 🚀

## Configuration

The configuration file can be published with:

```bash
php artisan vendor:publish --provider="Rapidez\Statamic\RapidezStatamicServiceProvider" --tag=config
```

After that, you'll find all options within `config/rapidez/statamic.php`

### Sites

Sites within Statamic will automatically be registered based on the Magento stores. So there is no need for a `sites.yaml`. The current site will be determined based on the `MAGE_RUN_CODE`, and the alternate hreflang link tags are grouped by the `website_code`

::: warning Sites cache
Make sure to flush the cache after editing stores in Magento!
:::

::: details Disable Statamic for a store
To disable Statamic for a specific store, just add the `store_code` to the `disabled_sites` within `config/rapidez/statamic.php`
:::

### Routing

The default Statamic routing will override the Rapidez routes. We don't want that, so you have to disable the default Statamic routing within `config/statamic/routes.php`

```php
'enabled' => false,
```

The integration package will register the Statamic routes as fallback, so it tries the Magento routes first.

::: tip Seeing a Magento page instead of Statamic?
This can happen when a CMS page in Magento has the same slug as a page in Statamic, like the homepage. To show the Statamic page, simply disable the page in Magento.
:::

### Assets

Make sure there is an assets disk within `config/filesystems.php`

```php
'disks' => [
    'assets' => [
        'driver' => 'local',
        'root' => public_path('assets'),
        'url' => '/assets',
        'visibility' => 'public',
    ],
],
```

## Content migration

The `statamic-content-migration:migrate-cms-pages` command migrates your Magento 2 CMS pages into Statamic's `pages` collection.
You can use this command as inspiration to create your own content migrations, like blog pages, or FAQ pages.

Optionally limit which pages are migrated with `--identifiers` (comma-separated Magento identifiers) and `--identifier-type` (`whitelist` or `blacklist`, default `whitelist`).

The ConvertField action will transform html into the bard component with the fieldName you pass.
It will use the CleanHtml action to transform messy Magento templates with widgets, variables, nested cms blocks into plain html.

:::tip
Don't like what your html turned into? You can add or remove cleaning steps in `config/rapidez/statamic/migration.php`
:::

## Runway / Magento data

With [Runway](https://github.com/statamic-rad-pack/runway), you're able to display data from an Eloquent model within Statamic. We're using this to have products, categories, and product attribute data from Magento visible within Statamic, without the need of importing and syncing data. These Runway models can be used to link anything within Statamic to existing Magento data.

Brands still use a Runway model under the hood (for example in relations), but the brands Runway resource is **hidden** in the control panel. You add and edit brand landing content as entries in the **`brands` collection** instead, so editors are not faced with two separate brand UIs.

For example, the product slider component within the page builder has a relation with the products Runway model. This way, you can select from all Magento products you'd like to display within the slider.

You can also enrich data with this; when you want to use Statamic to add data on product, category, or brand pages. When saving an entry we're not touching the Magento tables, those are always read-only! We are observing the "updating" event on those models and save all data to a Statamic entry. When retrieving a model we're doing the opposite; merging the data from Magento with the data from the Statamic entry so you still have a single merged view (for brands, that Statamic side is the `brands` collection entry linked to the Magento option).

### Displaying content

If you are going to enrich product or category pages with content from Statamic, you'll find the page builder field on the merged entry in `$content->content`.

To display the default page builder content, you have to add this to your view:

```blade
@includeWhen(isset($content), 'rapidez-statamic::page_builder', ['content' => $content?->content])
```

* Product: `resources/views/vendor/rapidez/product/overview.blade.php`
* Category: `resources/views/vendor/rapidez/category/overview.blade.php`

Brand landing pages use the same `rapidez-statamic::page_builder` partial, but the default blueprint exposes **two** page builder areas. The bundled brand view passes **`$content`** (top) and **`$bottom_content`** straight into the page builder include. Override `resources/views/vendor/rapidez-statamic/brands/show.blade.php` if you want a different layout around the listing.

::: details Disable `$content`
If you don't want `$content` on the product or category pages, you can disable it from the `config/rapidez/statamic.php` config file by setting `fetch.product` or `fetch.category` to `false`
:::

## Brand pages

Just make sure the `brand_attribute_id` is correct within `config/rapidez/statamic.php` so Magento knows which attribute represents a brand. Brand landing content (page builder above and below the product listing, plus SEO fields) lives in the **`brands` collection** in the control panel; the Runway brands resource is configured with `hidden` so you manage brands there only.

If you want to have actual brand pages on the frontend displaying all the products of that brand, you have to enable the route per store within `config/rapidez/statamic/builder.php`:

```php
'routes' => [
    Brands::class => [
        'store_code' => 'brand/{slug}'
    ],
],
```

For a "brand overview" page with all brands listed alphabetically, you can just create a normal page from the control panel and use the "brand overview" component.

::: details I'm using the Amasty ShopBy Brand module
Good news! There is an import command to import the data!

```bash
php artisan rapidez:statamic:import:brands
```

:::

## Navigation

To render a navigation somewhere we provide two options; a full main navigation option with a mobile sliderover menu + a helper with a unified cached output to render it yourself.

### Navigation helper

With Statamic you can get data by tag in Blade with:

```php
Statamic::tag('nav:footer')->fetch()
```

This will result in multiple queries to get all data. When you're linking to for example a category, each category will be a query resulting in a lot of queries. This package provides a "helper" that fetches the navigation completely with all children and the result will be unified and cached. When a navigation changes; the cache will be refreshed automatically.

```php
RapidezStatamic::nav('nav:footer')
```

::: details Example usage

```blade
<ul>
    @foreach (RapidezStatamic::nav('nav:footer') as $item)
        <li>
            <a href="{{ $item['url'] }}">
                {{ $item['title'] }}
            </a>
        </li>
        {{-- $item['children'] --}}
    @endforeach
</ul>
```

:::

### Main navigation

When you need a navigation from Statamic to be your site's main navigation in the header we provide a Blade component that handles everything for you:

```blade
<x-rapidez-statamic::nav
    nav="nav:main"
    {{-- Optionally a different mobile menu; of multiple combined --}}
    :mobileNav="['nav:main', 'nav:header_links']"
/>
```

In `resources/views/vendor/rapidez/layouts/partials/header.blade.php` replace the default Rapidez navigation with this component and you'll get a navigation displaying the main items in the header and the children within a "mega menu" dropdown on hover.

On mobile the whole menu will be in a slideover from [rapidez/blade-components](https://github.com/rapidez/blade-components); to open the mobile menu you've to add a opener somewhere and style this however you'd like:

```blade
<label for="navigation">
    Open mobile menu
</label>
```

## Globals

All Statamic globals will be available through the `$globals` variable within your Rapidez Blade templates. If you have a global with the handle "header" and added a field called "logo", it will be available as `$globals->header->logo`

## Forms

When you create a form, you can use `rapidez-statamic::emails.form` as the HTML template, which uses the [Laravel mail template](https://laravel.com/docs/12.x/mail#customizing-the-components) with all fields in a table. Make sure you enable markdown!

## Images

When using Rapidez Statamic, the package pre-integrates the [Glide directive package](https://github.com/justbetter/statamic-glide-directive) to work seamlessly with your Statamic install. It also pushes the Glide head partial onto the `rapidez::layouts.app` stack so the directive can load correctly. Just use the Glide directive as shown, and the package will handle image manipulation with the transformations dictated by your parameters.

```blade
@responsive($image, [
    'alt' => 'This is an alt text.', 
    'class' => 'some classes here',
    'loading' => 'lazy'
])
```

## Sitemap

This package hooks into the [Rapidez Sitemap](https://github.com/rapidez/sitemap) generation by adding Statamic-specific sitemaps to the store's sitemap index. For each store, we generate sitemaps for collections and taxonomies that have a route and content. The folder layout will look like:

```bash
rapidez-sitemaps/{store_id}/{sitemap_prefix}_collection_{collection_handle}.xml
rapidez-sitemaps/{store_id}/{sitemap_prefix}_taxonomy_{taxonomy_handle}.xml
```

With the [default rapidez/sitemap config](https://github.com/rapidez/sitemap/blob/master/config/sitemap.php), the prefix default is `statamic_sitemap_` and can be configured within `config/rapidez/statamic.php`

## Meta title and description

If you want to use Statamic for managing your meta title and description you will have to add it to your templates.
As an example, the category pages:
`vendor/rapidez/core/resources/views/category/overview.blade.php`

```diff
 @extends('rapidez::layouts.app')
 
- @section('title', $category->meta_title ?: $category->name)
- @section('description', $category->meta_description)
+ @section('title', $content?->meta_title ?: $category->meta_title ?: $category->name)
+ @section('description', $content?->meta_description ?: $category->meta_description)
 @section('canonical', url($category->url))
```

## Static caching

Statamic comes with [static caching](https://statamic.dev/static-caching) and this package adds the middleware for that. This means that when you configure static caching with Statamic, it will also be applied to all Rapidez routes.

::: details I'm using multiple stores
When using Statamic Static caching in a multisite setup, you typically need to [manually configure](https://statamic.dev/static-caching#paths) a path for each site for the static files to be stored. However, with Rapidez Statamic, this manual step isn't necessary. The integration automatically sets the correct paths based on the store definitions in the Magento database, saving you time and reducing potential errors.
:::

::: details Cloudflare Static Caching
Cloudflare's CDN edge can bring these static files even closer and faster to the customer. To achieve this you will need to create a [Cloudflare cache rule](../cache.md#cloudflare) and add a cache control header to your static route:

```nginx
location @static {
    add_header Cache-Control "max-age=120, stale-while-revalidate=3600";# [!code ++]
    try_files /static${uri}_$args.html $uri $uri/ /index.php?$args;
}
```

:::

Invalidation is handled by a command that checks the `updated_at` column on products, categories and pages in Magento. Everything updated after the latest invalidation will be invalidated:

```bash
php artisan rapidez-statamic:invalidate-cache
```

We recommend to schedule this command in `routes/console.php` to invalidate periodically. For more information, see [Task Scheduling](https://laravel.com/docs/12.x/scheduling).

```php
Schedule::command('rapidez-statamic:invalidate-cache')->everyFifteenMinutes();
```

You should also set up exclusions for a few routes in your `config/statamic/static_caching.php` config file:

```php
'exclude' => [
    'exclude' => [
        'class' => null,
        'urls' => [
            '/login',
            '/register',
            '/checkout',
            '/checkout/*',
        ],
    ],
]
```

You should add any other custom routes here that you don't want cached. Most importantly, any routes that will differ based on login state or cart state.

:::tip
You can use this package to make sure caches purged in Statamic also get purged in Cloudflare: [justbetter/statamic-cloudflare-purge](https://github.com/justbetter/statamic-cloudflare-purge).
:::

## Indexing

You can extend the `BaseEntry` model provided with this package to index your collection data into ElasticSearch. See the following example of a blog collection:

```php
<?php

namespace App\Models;

use Rapidez\Statamic\Models\BaseEntry;
use Statamic\Eloquent\Entries\Entry;

class Blog extends BaseEntry
{
    protected static $collection = 'blog';

    protected function getAdditionalIndexData(Entry $entry): array
    {
        return [
            'image' => $entry->image ? $entry->image->url() : '',
            'categories' => $entry->blog_categories->map(fn ($category) => [
                'title' => $category->title,
                'slug' => $category->slug,
            ]),
            'content' => is_array($entry->content) ? json_encode($entry->content) : $entry->content,
        ];
    }
}
```

Note the required definition of `$collection` here. This example also optionally adds some extra data to the indexer by using the `getAdditionalIndexData` function.

You will then also need to add this model into the `rapidez/models.php` config file, like so:

```diff
return [
    ...
+   'blog' => App\Models\Blog::class,
];
```

## Upgrading

### From 7.x to 8.x

::: details

Version 8 upgrades the integration to [Statamic 6](https://statamic.dev/) (and related dependencies such as Runway 9 and the Glide directive v4). Make sure your stack meets PHP 8.4, then run:

```bash
composer update rapidez/statamic -W
```

Follow Statamic's own upgrade guide for any control panel or content changes required by Statamic 6.
:::

---

---
url: /5.x/semantic-search.md
description: Need an even better search experience? Use Semantic search!
---

# Semantic Search

***

With semantic search, it's possible to understand the meaning of words by utilizing vector searches. You can get results with for example "clothing", even if that word isn't used in any product information. It understands that "shirt" or "pants" is related to "clothing". There are also multilingual machine learning models, so it's possible to search in multiple languages without the need to translate anything. For example, in Dutch; "kleding" or "tas voor op je rug" will also return results.

\[\[toc]]

## Preparation

Make sure you're familiar with [InstantSearch](https://github.com/algolia/instantsearch), as it's used for the autocomplete and product listings such as category pages, the search page and product sliders. [Indexing](indexer.md) is handled by [Laravel Scout](https://laravel.com/docs/12.x/scout) and to make [InstantSearch](https://github.com/algolia/instantsearch) compatible with [Elasticsearch](https://www.elastic.co/elasticsearch) / [OpenSearch](https://opensearch.org) we're using [Searchkit](https://github.com/searchkit/searchkit). More docs on related topics:

* [Requirements](installation.md#requirements)
* Elasticsearch: [configuration](configuration.md#elasticsearch), [CORS](installation.md#elasticsearch) and [secure](deployment.md#secure-elasticsearch)
* OpenSearch: [configuration](configuration.md#opensearch), [CORS](installation.md#opensearch) and [secure](deployment.md#secure-opensearch)
* [Listing component](theming.md#listing-component)
* [Extending the autocomplete](extending.md#autocomplete)
* [Eventy filters](package-development.md#eventy-filters)

## Requirements

It's possible to use semantic search with Elasticsearch and OpenSearch. With OpenSearch, it's a free feature to load a machine learning model into OpenSearch which creates the vectors. For Elasticsearch, you need to handle vector creation yourself or use a paid subscription.

## Configuration

### Elasticsearch

Have a look at the [semantic search Searchkit docs](https://www.searchkit.co/docs/tutorials/semantic-search). Keep in mind this requires a paid subscription! More info in the [Elasticsearch semantic search docs](https://www.elastic.co/docs/solutions/search/semantic-search).

### OpenSearch

Follow [this gist](https://gist.github.com/dtaivpp/d7e8d8a3ee5debaf896ed2f45b915ad3), [read the linked blog](https://tippybits.com/should-you-be-doing-vector-search/) or check out [this Youtube video](https://www.youtube.com/watch?v=lpQiJGpeeWU). But also check the [OpenSearch docs about semantic search](https://docs.opensearch.org/docs/latest/vector-search/ai-search/semantic-search/) and the [semantic search tutorial](https://docs.opensearch.org/docs/latest/tutorials/vector-search/neural-search-tutorial/).

### Sentence Transformers

With the configuration of Elasticsearch / OpenSearch you'll need to pick a sentence transformer model. The defaults in the tutorials are pretty good but you have to experiment with different models to see which one returns the best results for you. [More info on pretrained models](https://www.sbert.net/docs/sentence_transformer/pretrained_models.html) and if you're looking for a multilingual model; [switch to a different model that supports multiple languages](https://www.sbert.net/docs/sentence_transformer/pretrained_models.html#multilingual-models)

## Installation

::: info NOTE
These examples are using OpenSearch!
:::

### Backend

The easiest way to install semantic search capabilities within Rapidez is with [Eventy filters](package-development.md#eventy-filters) from your `AppServiceProvider`. First you need to add these index settings:

```php
Eventy::addFilter('index.product.settings', fn ($settings) => array_merge_recursive($settings, [
    'index.knn' => true,
    'default_pipeline' => 'embedding-ingest-pipeline',
    'index.search.default_pipeline' => 'hybrid-search-pipeline'
]));
```

Create an extra field with all data you'd like to be used for the vector. With the Magento sample data you could do something like this:

```php
Eventy::addFilter('index.product.data', fn ($data) => array_merge_recursive($data, [
    'content' => implode(' - ', [
        'Product name: '.$data['name'],
        'SKU: '.$data['sku'],
        'Price: '.$data['price'].' euro',
        'Activity: '.implode(', ', $data['activity'] ?? []),
        'Material: '.implode(', ', $data['material'] ?? []),
        'Style general: '.implode(', ', $data['style_general'] ?? []),
        'Style bottom: '.implode(', ', $data['style_bottom'] ?? []),
        'Climate: '.implode(', ', $data['climate'] ?? []),
        'Pattern: '.implode(', ', $data['pattern'] ?? []),
        'Gender: '.implode(', ', $data['gender'] ?? []),
        'Description: '.strip_tags($data['description']),
    ]
)]));
```

Experiment with different data or split data in multiple fields so it's possible to search independently and apply boosts on certain data. This field also needs a mapping:

```php
Eventy::addFilter('index.product.mapping', fn ($mapping) => array_merge_recursive($mapping, [
    'properties' => [
        'content_embedding' => [
            'type' => 'knn_vector',
            'dimension' => 512,
            'method' => [
                'name' => 'hnsw',
                'space_type' => 'innerproduct',
                'engine' => 'faiss',
            ]
        ],
    ],
]));
```

::: info NOTE
Keep in mind this needs to match with your model and configurations within OpenSearch!

[More info on methods and engines](https://docs.opensearch.org/docs/latest/field-types/supported-field-types/knn-methods-engines/)
:::

Now everything is configured, run the [indexer](indexer.md):

```bash
php artisan rapidez:index
```

::: tip
Alternatively if you've [overwritten the product model](extending.md#models) you can use these methods within the product model instead of using Eventy:

* `indexMapping()`
* `indexSettings()`
* `toSearchableArray()`

See the [Laravel Scout docs](https://laravel.com/docs/12.x/scout), the [extending indexer docs](indexer.md#model) and the current [searchable trait](https://github.com/rapidez/core/blob/master/src/Models/Traits/Product/Searchable.php) used by the [product model](https://github.com/rapidez/core/blob/master/src/Models/Product.php).
:::

### Frontend

The query used to get search results needs to include our new vector field. You can overwrite the default query using the `query` prop on the [listing component](theming.md#listing-component). First [publish the Blade template](theming.md#views) and edit: `resources/views/vendor/rapidez/components/listing.blade.php`

Add a new custom function name:

```php
<listing
    ...
    :query="semanticSearch" // [!code focus]
>
```

And create that function in `resources/js/app.js`:

```js
Vue.prototype.semanticSearch = (query, searchAttributes, config) => {
    let finalQuery = Vue.prototype.relevanceQueryMatch(query, searchAttributes, config.fuzziness)

    finalQuery.bool.should.push({
        'neural': {
            'content_embedding': {
                'query_text': query,
                'model_id': 'YOUR-MODEL-ID',
                'min_score': 0.9,
            }
        }
    })

    return finalQuery
}
```

::: tip
Refer to the [OpenSearch docs on neural queries](https://docs.opensearch.org/docs/latest/query-dsl/specialized/neural/)
:::

:::: warning Temporary workaround
Until [this pull request](https://github.com/searchkit/searchkit/pull/1408) is merged you also need to add this so we can use the default query.
::: details relevanceQueryMatch function

```js
// From: https://github.com/searchkit/searchkit/blob/main/packages/searchkit/src/transformRequest.ts
// See: https://github.com/searchkit/searchkit/pull/1408
Vue.prototype.relevanceQueryMatch = (query, search_attributes, fuzziness = "AUTO:4,8") => {
    const getFieldsMap = (boostMultiplier) => {
        return search_attributes.map((attribute) => {
            return typeof attribute === "string" ? attribute : `${attribute.field}^${(attribute.weight || 1) * boostMultiplier}`;
        });
    };
    return {
        bool: {
            should: [
                {
                    bool: {
                        should: [
                            {
                                multi_match: {
                                    query,
                                    fields: getFieldsMap(1),
                                    fuzziness
                                }
                            },
                            {
                                multi_match: {
                                    query,
                                    fields: getFieldsMap(0.5),
                                    type: "bool_prefix"
                                }
                            }
                        ]
                    }
                },
                {
                    multi_match: {
                        query,
                        type: "phrase",
                        fields: getFieldsMap(2)
                    }
                }
            ]
        }
    };
}
```

:::
::::